> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ensads.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# ENS Ads Campaign Objects: Fields, Statuses & Matching

> Campaigns are the core ad unit in ENS Ads. Learn each field an object contains and how placement and targeting parameters control which campaigns are returned.

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:

<ResponseField name="id" type="integer" required>
  Unique numeric identifier for the campaign. Use this value when tracking impressions and clicks.
</ResponseField>

<ResponseField name="title" type="string" required>
  The campaign's display title, provided by the advertiser.
</ResponseField>

<ResponseField name="description" type="string">
  A short description of the campaign or offer.
</ResponseField>

<ResponseField name="category" type="string">
  The content category the campaign is associated with. See [Targeting](/concepts/targeting) for the full list of supported categories.
</ResponseField>

<ResponseField name="destinationUrl" type="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.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current state of the campaign. See [campaign statuses](#campaign-statuses) below.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp indicating when the campaign was created.
</ResponseField>

## Sample campaign object

The following is an example campaign object as returned inside the `data` array of a successful response:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

<AccordionGroup>
  <Accordion title="running">
    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.
  </Accordion>
</AccordionGroup>

<Note>
  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.
</Note>

## 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        |

<Tip>
  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.
</Tip>