> ## 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 Quick Start: Your First Ad API Integration

> Go from zero to a working ad integration in minutes. Fetch a live campaign, display it in a placement, and record your first impression and click events.

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](https://ads.enslive.live) before you begin.

<Steps>
  <Step title="Get your API key">
    Sign in to the [ENS Ads dashboard](https://ads.enslive.live) and copy your API key. Store it as an environment variable so it is never hardcoded in your source files:

    ```bash theme={null}
    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](/authentication) for full details.
  </Step>

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

    ```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 an array of matching campaigns:

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

    Pick the first campaign from `data` to display. Note the `id` — you will use it in the next two steps.
  </Step>

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

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

    ```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 the event was recorded:

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

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

  <Step title="Track a click">
    When a user clicks the campaign, call `POST /campaigns/click` with the same parameters:

    ```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"
      }'
    ```

    ```json theme={null}
    {
      "status": "success",
      "message": "Click tracked successfully"
    }
    ```

    After recording the click, redirect the user to the campaign's `destinationUrl`.
  </Step>
</Steps>

## What's next

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

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api/fetch-campaigns">
    Full parameter and response documentation for all three endpoints.
  </Card>

  <Card title="Integration guide" icon="plug" href="/guides/integration">
    A production-ready walkthrough covering error handling, targeting, and placements.
  </Card>

  <Card title="Error handling" icon="triangle-alert" href="/guides/error-handling">
    Understand every error response and how to handle it gracefully.
  </Card>

  <Card title="Placements" icon="layout" href="/concepts/placements">
    Browse all supported placement IDs and their descriptions.
  </Card>
</CardGroup>