API Documentation

Authentication

Every request requires a Bearer API key. Keys start with fd_live_ and are shown once at creation — only a SHA-256 hash is stored.

Authorization: Bearer fd_live_your_api_key

Base URL

https://fandistrictos.com/api/v1

Rate limits

Limits depend on your plan (per-minute and per-day). Every response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1789580000

When exceeded, the API returns 429 with code RATE_LIMITED.

Error format

{ "error": "string", "code": "RATE_LIMITED | UNAUTHORIZED | NOT_FOUND | INVALID_SCOPE | PLAN_REQUIRED | BAD_REQUEST" }

Endpoints

GET/api/v1/fanpass/verifyfanpass.verify

Verify a fan's pass and return their public profile — never PII.

curl -X GET "https://fandistrictos.com/api/v1/fanpass/verify?fan_id=<fan_pass_uuid>" \
  -H "Authorization: Bearer fd_live_your_api_key"

{
  "verified": true,
  "fan_pass_id": "9c1f…",
  "tier": "district",
  "member_since": "2026-01-15",
  "welcome_drink_eligible": true,
  "check_in_count": 12,
  "preferences": ["cocktails", "sports-bars"]
}

POST/api/v1/pulse/intentpulse.intent

Submit a fan intent to PULSE and receive an AI-curated itinerary.

{
  "fan_pass_id": "<fan_pass_uuid>",
  "intent": "Saints game day for 4 people tonight",
  "location": { "lat": 29.9511, "lng": -90.0715 },
  "event_id": "<optional_event_uuid>",
  "party_size": 4
}

{
  "itinerary_id": "itin_…",
  "summary": "Game Day Plan — Saints vs Jaguars",
  "items": [
    { "type": "reservation", "venue_name": "Cochon", "time": "6:00 PM",
      "offer": "10% off with District Pass",
      "book_url": "https://fandistrictos.com/fan/reserve/venue_xxx" }
  ],
  "sponsor_offers": [
    { "brand": "Texas Black Gold Distillery", "offer": "$15 credit on first cocktail", "value_cents": 1500 }
  ]
}

POST/api/v1/agent/deployagent.deploy

Deploy a branded Business Agent for any venue. Growth or Enterprise plan required.

{
  "venue_name": "The Rusty Nail",
  "venue_address": "1100 Constance St, New Orleans, LA",
  "contact_email": "manager@therustynail.com",
  "branding": { "tagline": "Your game day home base", "logo_url": "https://…" },
  "capabilities": ["reservations", "offers", "fan_pass_verification"]
}

{
  "agent_id": "…",
  "venue_id": "…",
  "embed_script": "<script src='https://fandistrictos.com/embed/agent/…'></script>",
  "dashboard_url": "https://fandistrictos.com/venue/agent?id=…",
  "status": "active"
}

GET/api/v1/outcomesoutcomes.read

Verified outcome data for a sponsor campaign. Owner-scoped.

curl -X GET "https://fandistrictos.com/api/v1/outcomes?campaign_id=<uuid>&from=2026-08-01&to=2026-08-15" \
  -H "Authorization: Bearer fd_live_your_api_key"

{
  "campaign_id": "…",
  "brand": "Texas Black Gold Distillery",
  "period": { "from": "2026-08-01", "to": "2026-08-15" },
  "verified_outcomes": 847,
  "total_spend": 12705.00,
  "cost_per_outcome": 15.00,
  "top_venues": ["The Rusty Nail", "Cochon"],
  "fan_demographics": { "avg_check_ins": 3.2, "top_events": ["Saints vs Jaguars"] }
}

Webhooks

Register webhooks from your dashboard. Events: reservation.confirmed, outcome.verified, pass.activated, agent.deployed. Each delivery is signed with an HMAC-SHA256 header you verify with your signing secret:

// Node.js verification
const crypto = require("crypto");
const expected = crypto
  .createHmac("sha256", process.env.FD_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-fandistrict-signature"] ?? "")
);

{
  "event": "outcome.verified",
  "created_at": "2026-08-15T21:04:00Z",
  "data": { "campaign_id": "…", "outcome_type": "check_in", "venue_id": "…" }
}

SDKs

Coming soon: Node.js, Python, Ruby.