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

# How to Integrate ENS Ads into Your Platform (5 Steps)

> Step-by-step guide to integrating ENS Ads: fetch campaigns, validate targeting, render in the correct placement, and report impressions and clicks to the API.

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.

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

<Steps>
  <Step title="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.

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

    ```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
    }
    ```
  </Step>

  <Step title="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.

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

  <Step title="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.
  </Step>

  <Step title="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.

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

    ```json theme={null}
    {
      "status": "success",
      "message": "Impression tracked successfully"
    }
    ```
  </Step>

  <Step title="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.

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

    ```json theme={null}
    {
      "status": "success",
      "message": "Click tracked successfully"
    }
    ```
  </Step>
</Steps>