Ads

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.

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

POST /api/ads/generate-draft

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

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

string

google, facebook, or linkedin. Defaults to google.

string

simple or advanced. Defaults to simple.

object

Optional voice and music preference for video creative.

{
  "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.

curl "https://app.neariq.io/api/ads/google/campaigns" \
  -H "Cookie: <dashboard session cookie>"

{
  "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.

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

{
  "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.

curl "https://app.neariq.io/api/ads/meta/campaigns" \
  -H "Cookie: <dashboard session cookie>"

{
  "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.

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

{
  "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.

curl "https://app.neariq.io/api/ads/linkedin/campaigns" \
  -H "Cookie: <dashboard session cookie>"

{
  "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.

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

{
  "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.

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

{
  "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.

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

{
  "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.

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

{
  "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

API Reference

Endpoints

Webhooks

POST /api/ads/generate-draft

GET /api/ads/google/campaigns

POST /api/ads/google/campaigns

GET /api/ads/meta/campaigns

POST /api/ads/meta/campaigns

GET /api/ads/linkedin/campaigns

POST /api/ads/linkedin/campaigns

GET /api/ads/google/performance

GET /api/ads/meta/performance

GET /api/ads/linkedin/performance

Errors

​POST /api/ads/generate-draft

​GET /api/ads/google/campaigns

​POST /api/ads/google/campaigns

​GET /api/ads/meta/campaigns

​POST /api/ads/meta/campaigns

​GET /api/ads/linkedin/campaigns

​POST /api/ads/linkedin/campaigns

​GET /api/ads/google/performance

​GET /api/ads/meta/performance

​GET /api/ads/linkedin/performance

​Errors

POST /api/ads/generate-draft

GET /api/ads/google/campaigns

POST /api/ads/google/campaigns

GET /api/ads/meta/campaigns

POST /api/ads/meta/campaigns

GET /api/ads/linkedin/campaigns

POST /api/ads/linkedin/campaigns

GET /api/ads/google/performance

GET /api/ads/meta/performance

GET /api/ads/linkedin/performance

Errors