Skip to main content

​
Consumer API Overview

The Consumer API enables end-user interactions with Fanfare experiences, including joining queues, entering draws, placing auction bids, and checking participation status.

​
Base URL

https://consumer.fanfare.io/api/v1

​
Authentication

The Consumer API supports multiple authentication methods depending on the use case:

​
Publishable Key (Client-Side)

For browser and mobile app integrations: 
X-Publishable-Key: pk_live_xxxxxxxxxxxx

​
Consumer Access Token

After authentication (OTP, external auth), include the access token: 
Authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...

​
Secret Key (Server-Side)

For server-to-server calls (requires secret key): 
Authorization: Bearer sk_live_xxxxxxxxxxxx

​
API Endpoints

​
Authentication

MethodEndpointDescription
POST/auth/guestCreate guest session
POST/auth/otp/requestRequest OTP code
POST/auth/otp/verifyVerify OTP and authenticate
POST/auth/external/authorizeCreate external auth exchange code
POST/auth/external/exchangeExchange code for session
POST/auth/refreshRefresh access token
POST/auth/logoutInvalidate session

​
Experiences

MethodEndpointDescription
GET/experiences/:experienceIdGet experience details
POST/experiences/:experienceId/enterEnter an experience
DELETE/experiences/:experienceId/leaveLeave an experience

​
Queues

MethodEndpointDescription
GET/queues/:queueIdGet queue details
POST/queues/:queueId/enterEnter a queue
POST/queues/:queueId/leaveLeave a queue
GET/queues/:queueId/statusGet consumer’s queue status
POST/queues/:queueId/admitAdmit consumer (secret key)
POST/queues/:queueId/completeComplete admission (secret key)
POST/queues/:queueId/denyDeny consumer (secret key)
POST/queues/:queueId/validateValidate admission token (secret key)

​
Draws (Lotteries)

MethodEndpointDescription
GET/draws/:drawIdGet draw details
POST/draws/:drawId/enterEnter a draw
POST/draws/:drawId/leaveLeave a draw
GET/draws/:drawId/statusGet consumer’s draw status
POST/draws/:drawId/completeComplete draw win (secret key)
POST/draws/:drawId/denyDeny consumer (secret key)
POST/draws/:drawId/validateValidate win token (secret key)

​
Auctions

MethodEndpointDescription
GET/auctions/:auctionIdGet auction details
POST/auctions/:auctionId/bidPlace a bid
GET/auctions/:auctionId/statusGet consumer’s bid status
GET/auctions/:auctionId/highest-bidGet current highest bid
GET/auctions/:auctionId/bids/historyGet consumer’s bid history
GET/auctions/:auctionId/bidsGet all bids (authenticated)

​
Timed Releases

MethodEndpointDescription
GET/timed-releases/:timedReleaseIdGet timed release details
POST/timed-releases/:timedReleaseId/enterEnter a timed release
GET/timed-releases/:timedReleaseId/statusGet consumer’s status

​
Appointments

MethodEndpointDescription
GET/appointments/:appointmentIdGet appointment details
GET/appointments/:appointmentId/slotsGet available slots
POST/appointments/:appointmentId/bookBook an appointment
DELETE/appointments/:appointmentId/cancelCancel appointment

​
Consumers

MethodEndpointDescription
GET/consumers/meGet current consumer with active participations
GET/consumers/:idGet consumer by ID (secret key)

​
Organizations

MethodEndpointDescription
GET/organizations/currentGet current organization settings

​
Waitlists

MethodEndpointDescription
POST/waitlists/:waitlistId/enterEnter a waitlist
GET/waitlists/:waitlistId/statusGet waitlist status

​
Common Response Patterns

​
Distribution Status Response

All distribution types (queues, draws, auctions) return a consistent status structure: 
interface DistributionStatus {
  status: "QUEUED" | "ADMITTED" | "COMPLETED" | "DENIED" | "LEFT";
  enteredAt?: string;
  admittedAt?: string;
  completedAt?: string;
  denyReason?: string;
  position?: number;
  admissionToken?: string;
}

​
Experience Response

interface Experience {
  id: string;
  name: string;
  openAt: string | null;
  closeAt: string | null;
  timeZone: string | null;
  theme: ExperienceTheme | null;
  sequences: Sequence[];
}

​
Device Fingerprinting

For bot mitigation, some endpoints require device fingerprints: 
X-Fingerprint: fp_01HXYZ123456789
Fingerprint validation is enforced on:
  • Queue entry
  • Draw entry
  • Auction bidding
  • Admission validation

​
Rate Limits

Consumer API rate limits per organization:
Endpoint CategoryLimitWindow
Queue Entry1000/min1 minute
Draw Entry1000/min1 minute
Auction Bids500/min1 minute
Status Checks5000/min1 minute
Authentication100/min1 minute

​
SDK Integration

​
JavaScript/TypeScript SDK

import { Fanfare, useQueue } from "@fanfare/sdk-react";

// Initialize
const fanfare = new Fanfare({
  publishableKey: "pk_live_xxxxxxxxxxxx",
});

// React Hook
function QueueComponent({ queueId }: { queueId: string }) {
  const { status, enter, leave, isLoading } = useQueue(queueId);

  if (status?.status === "ADMITTED") {
    return <div>You're in! Token: {status.admissionToken}</div>;
  }

  return (
    <button onClick={enter} disabled={isLoading}>
      Join Queue
    </button>
  );
}

​
Direct API Usage

// Enter a queue
const response = await fetch("https://consumer.fanfare.io/api/v1/queues/queue_01HXYZ123456789/enter", {
  method: "POST",
  headers: {
    "X-Publishable-Key": "pk_live_xxxxxxxxxxxx",
    Authorization: `Bearer ${accessToken}`,
    "X-Fingerprint": fingerprint,
    "Content-Type": "application/json",
  },
});

const status = await response.json();
console.log(status);
// { status: "QUEUED", position: 42, enteredAt: "2024-12-01T09:00:00Z" }

​
Error Handling

Common Consumer API errors:
ErrorDescriptionHTTP Code
Authentication requiredMissing or invalid credentials401
Consumer ID is requiredNo authenticated consumer400
Queue not foundInvalid queue ID404
Queue is not open yetQueue opens in the future423
Queue is fullQueue at capacity429
Auction is closedAuction has ended400

​
Next Steps