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

# Ads

> Session-authenticated ad campaign draft, saved campaign, and performance endpoints.

Ads endpoints power the dashboard campaign builder. They use the signed-in app session, not `X-NearIQ-Key`. Ad campaign creation requires a plan with ad campaign access. Drafts are saved for review; users remain in control before publishing.

<Note>
  NearIQ drafts campaign structure, copy, budgets, and targeting from stored business and competitor context. Users should review and edit all ad content before publishing.
</Note>

## POST /api/ads/generate-draft

Generates an ad campaign draft for a selected platform and mode.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.neariq.io/api/ads/generate-draft" \
    -H "Content-Type: application/json" \
    -H "Cookie: <dashboard session cookie>" \
    -d '{
      "platform": "google",
      "mode": "simple",
      "creativeAudio": {
        "voice": "warm",
        "music": "upbeat",
        "speechPace": "normal"
      }
    }'
  ```
</RequestExample>

<ParamField body="platform" type="string">
  `google`, `facebook`, or `linkedin`. Defaults to `google`.
</ParamField>

<ParamField body="mode" type="string">
  `simple` or `advanced`. Defaults to `simple`.
</ParamField>

<ParamField body="creativeAudio" type="object">
  Optional voice and music preference for video creative.
</ParamField>

```json theme={null}
{
  "draft": {
    "platform": "google",
    "name": "Austin Pilates Intro Offer",
    "objective": "Drive bookings for intro classes in South Austin.",
    "keywords": ["pilates austin", "reformer pilates near me"],
    "headlines": ["Try Pilates Today", "Austin Reformer Class"],
    "descriptions": ["Book a starter class with coached support."],
    "dailyBudget": 25,
    "duration": "2 weeks",
    "targeting": "5-mile radius around South Austin"
  }
}
```

## GET /api/ads/google/campaigns

Lists saved Google campaign drafts for the active business.

```bash theme={null}
curl "https://app.neariq.io/api/ads/google/campaigns" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "campaigns": [
    {
      "id": "fb079bd8-2671-4f2c-965f-a6f0a05254b8",
      "platform": "google",
      "name": "Austin Pilates Intro Offer",
      "daily_budget": 25,
      "created_at": "2026-05-30T18:00:00.000Z"
    }
  ],
  "configured": true,
  "accountConnected": false
}
```

## POST /api/ads/google/campaigns

Saves a Google campaign draft.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/ads/google/campaigns" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "name": "Austin Pilates Intro Offer",
    "headlines": ["Try Pilates Today", "Austin Reformer Class"],
    "descriptions": ["Book a starter class with coached support."],
    "keywords": ["pilates austin", "reformer pilates near me"],
    "dailyBudget": 25,
    "targetingLocation": "Austin, TX"
  }'
```

```json theme={null}
{
  "status": "draft_created",
  "configured": true,
  "accountConnected": false,
  "message": "Campaign draft saved. Connect your Google Ads account to publish.",
  "campaign": {
    "id": "fb079bd8-2671-4f2c-965f-a6f0a05254b8",
    "platform": "google",
    "name": "Austin Pilates Intro Offer"
  }
}
```

## GET /api/ads/meta/campaigns

Lists saved Facebook and Instagram campaign drafts for the active business.

```bash theme={null}
curl "https://app.neariq.io/api/ads/meta/campaigns" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "campaigns": [
    {
      "id": "79a5ec3e-006d-407a-85c7-4cd5775d9f09",
      "platform": "facebook",
      "name": "New Member Trial",
      "daily_budget": 20
    }
  ],
  "configured": true,
  "accountConnected": false
}
```

## POST /api/ads/meta/campaigns

Saves a Facebook or Instagram campaign draft.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/ads/meta/campaigns" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "name": "New Member Trial",
    "headlines": ["Start Strong This Week"],
    "descriptions": ["Join a coached small-group class near you."],
    "dailyBudget": 20,
    "targetingInterests": ["fitness", "wellness"],
    "placements": ["facebook_feed", "instagram_feed"]
  }'
```

```json theme={null}
{
  "status": "draft_created",
  "configured": true,
  "accountConnected": false,
  "message": "Campaign draft saved. Connect your Meta Business Manager to publish.",
  "campaign": {
    "id": "79a5ec3e-006d-407a-85c7-4cd5775d9f09",
    "platform": "facebook",
    "name": "New Member Trial"
  }
}
```

## GET /api/ads/linkedin/campaigns

Lists saved LinkedIn campaign drafts for the active business.

```bash theme={null}
curl "https://app.neariq.io/api/ads/linkedin/campaigns" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "campaigns": [
    {
      "id": "a1d4925b-1040-4bf8-8e9f-091f86dd6d09",
      "platform": "linkedin",
      "name": "Employer Wellness Offer",
      "daily_budget": 25
    }
  ],
  "configured": true,
  "accountConnected": true
}
```

## POST /api/ads/linkedin/campaigns

Saves a LinkedIn campaign draft. Paid launch remains review-controlled; NearIQ does not auto-spend from this endpoint.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/ads/linkedin/campaigns" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "name": "Employer Wellness Offer",
    "headlines": ["Team Wellness in Austin"],
    "descriptions": ["Reach local employers with coached wellness programs."],
    "dailyBudget": 25,
    "targetingTitles": ["Founder", "HR Manager"],
    "targetingIndustries": ["Health, Wellness and Fitness"]
  }'
```

```json theme={null}
{
  "status": "draft_created",
  "configured": true,
  "accountConnected": false,
  "message": "LinkedIn campaign draft saved. Connect LinkedIn Ads to review and publish from the ad account.",
  "campaign": {
    "id": "a1d4925b-1040-4bf8-8e9f-091f86dd6d09",
    "platform": "linkedin",
    "name": "Employer Wellness Offer"
  }
}
```

## GET /api/ads/google/performance

Returns stored Google ads freshness and performance summaries for the active business.

```bash theme={null}
curl "https://app.neariq.io/api/ads/google/performance?refresh=1" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "platform": "google",
  "status": "fresh",
  "metrics": {
    "impressions": 4200,
    "clicks": 188,
    "spend": 260
  }
}
```

## GET /api/ads/meta/performance

Returns stored Facebook and Instagram ads freshness and performance summaries for the active business.

```bash theme={null}
curl "https://app.neariq.io/api/ads/meta/performance?refresh=1" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "platform": "meta",
  "status": "stale",
  "metrics": {
    "impressions": 3200,
    "clicks": 101,
    "spend": 180
  }
}
```

## GET /api/ads/linkedin/performance

Returns stored LinkedIn ads freshness and performance summaries for the active business.

```bash theme={null}
curl "https://app.neariq.io/api/ads/linkedin/performance?refresh=1" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "platform": "linkedin",
  "syncStatus": "pending",
  "summary": {
    "impressions": 0,
    "clicks": 0,
    "conversions": 0,
    "spend": 0
  }
}
```

## Errors

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `400`  | Invalid JSON or missing campaign fields        |
| `401`  | Missing dashboard session                      |
| `403`  | Plan does not include ad campaigns             |
| `404`  | No active business found                       |
| `500`  | Draft generation or save failed                |
| `503`  | Connected ad account support is not configured |