Skip to main content
This guide walks you through a complete ad delivery cycle using the ENS Ads API. By the end you will have fetched a live campaign, displayed it in a placement, and reported both an impression and a click. All you need is your API key — get one from the ENS Ads dashboard before you begin.
1

Get your API key

Sign in to the ENS Ads dashboard and copy your API key. Store it as an environment variable so it is never hardcoded in your source files:
export ENS_ADS_API_KEY="YOUR_API_KEY"
Every request you make will include this key in the Authorization header as a Bearer token. See Authentication for full details.
2

Fetch your first campaigns

Call GET /campaigns/fetch with the placement parameter to retrieve campaigns targeted to that slot. The placement value must match one of the predefined placement IDs — header_banner is a good starting point.
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 an array of matching campaigns:
{
  "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
}
Pick the first campaign from data to display. Note the id — you will use it in the next two steps.
3

Display the campaign

Render the campaign in your UI using the fields returned by the fetch response:
  • Use title and description as the ad copy.
  • Link to destinationUrl so the user is taken to the advertiser’s page when they click.
  • Place the ad in the header_banner slot (or whichever placement you requested).
Make sure the campaign is visible to the user before you record an impression in the next step.
4

Track an impression

Once the campaign is rendered and visible, call POST /campaigns/impression to record the display event. Pass the same placement, location, and device values you 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 the event was recorded:
{
  "status": "success",
  "message": "Impression tracked successfully"
}
Track one impression per campaign display, not per page load. If you show the same campaign multiple times on a single page, record multiple impressions accordingly.
5

Track a click

When a user clicks the campaign, call POST /campaigns/click with the same parameters:
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"
  }'

{
  "status": "success",
  "message": "Click tracked successfully"
}
After recording the click, redirect the user to the campaign’s destinationUrl.

​
What’s next

You have completed a full ad delivery cycle. Explore the guides below to go deeper:

API reference

Full parameter and response documentation for all three endpoints.

Integration guide

A production-ready walkthrough covering error handling, targeting, and placements.

Error handling

Understand every error response and how to handle it gracefully.

Placements

Browse all supported placement IDs and their descriptions.