Skip to main content

Consumer Identity API

Endpoints for managing consumer identity, profile, and active participations.

Get Current Consumer

Retrieve the current authenticated consumer’s profile and all active participations across experiences. GET /api/v1/consumers/me

Authentication

  • Publishable key required
  • Consumer authentication required

Response

interface ConsumerMe {
  id: string;
  email: string | null;
  phone: string | null;
  fullName: string | null;
  createdAt: string;
  active: ActiveParticipations;
}

interface ActiveParticipations {
  experiences: Record<string, ExperienceNode>;
  queues: Record<string, QueueState>;
  draws: Record<string, DrawState>;
  auctions: Record<string, AuctionState>;
  timedReleases: Record<string, TimedReleaseState>;
  admissions: Record<string, Admission>;
  journeys: JourneyResume[];
}

interface JourneyResume {
  experienceId: string;
  sequenceId: string;
  journeyStage: "routed" | "admitted";
  sequenceStage: "waitlist_entered" | "participating" | "admitted";
  participation: {
    type: "waitlist" | "queue" | "draw" | "auction" | "timed_release";
    id: string;
    status: string;
    admissionToken?: string;
  };
  admission?: {
    distributionType: string;
    distributionId: string;
    experienceId: string;
    sequenceId: string;
    admissionToken: string;
    admittedAt: string;
  };
}

Example

curl -X GET https://consumer.fanfare.io/api/v1/consumers/me \
  -H "X-Publishable-Key: pk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
Response:
{
  "id": "cons_01HXYZ123456789",
  "email": "[email protected]",
  "phone": null,
  "fullName": "John Doe",
  "createdAt": "2024-11-15T10:00:00Z",
  "active": {
    "experiences": {
      "exp_01HXYZ123456789": {
        "sequences": {
          "seq_01HXYZ123456789": {
            "queue": {
              "queueId": "queue_01HXYZ123456789",
              "sequenceId": "seq_01HXYZ123456789",
              "status": "ADMITTED",
              "enteredAt": "2024-12-01T09:05:00Z",
              "admittedAt": "2024-12-01T09:15:00Z",
              "admissionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
            }
          }
        }
      }
    },
    "queues": {
      "queue_01HXYZ123456789": {
        "queueId": "queue_01HXYZ123456789",
        "status": "ADMITTED",
        "position": 0,
        "enteredAt": "2024-12-01T09:05:00Z",
        "admittedAt": "2024-12-01T09:15:00Z",
        "admissionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
      }
    },
    "draws": {},
    "auctions": {},
    "timedReleases": {},
    "admissions": {},
    "journeys": [
      {
        "experienceId": "exp_01HXYZ123456789",
        "sequenceId": "seq_01HXYZ123456789",
        "journeyStage": "admitted",
        "sequenceStage": "admitted",
        "participation": {
          "type": "queue",
          "id": "queue_01HXYZ123456789",
          "status": "ADMITTED",
          "admissionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
        },
        "admission": {
          "distributionType": "queue",
          "distributionId": "queue_01HXYZ123456789",
          "experienceId": "exp_01HXYZ123456789",
          "sequenceId": "seq_01HXYZ123456789",
          "admissionToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
          "admittedAt": "2024-12-01T09:15:00Z"
        }
      }
    ]
  }
}

Error Responses

StatusErrorDescription
401Authentication requiredMissing or invalid consumer authentication
404Consumer not foundConsumer ID does not exist

Get Consumer by ID (Server-Side)

Retrieve a consumer by ID. Requires secret key. GET /api/v1/consumers/:id

Authentication

  • Secret key required

Path Parameters

ParameterTypeDescription
idstringThe consumer ID

Response

interface Consumer {
  id: string;
  email: string | null;
  phone: string | null;
  fullName: string | null;
  createdAt: string;
}

Example

curl -X GET https://consumer.fanfare.io/api/v1/consumers/cons_01HXYZ123456789 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
Response:
{
  "id": "cons_01HXYZ123456789",
  "email": "[email protected]",
  "phone": "+12025551234",
  "fullName": "John Doe",
  "createdAt": "2024-11-15T10:00:00Z"
}

Error Responses

StatusErrorDescription
401Secret key requiredMissing or invalid secret key
404Consumer not foundConsumer ID does not exist

Understanding Active Participations

The /consumers/me endpoint returns all active participations, which helps the SDK resume consumer journeys.

Journey Stages

StageDescription
routedConsumer has been directed to a distribution (waiting in queue, entered draw, etc.)
admittedConsumer has been admitted and can proceed to checkout

Sequence Stages

StageDescription
waitlist_enteredConsumer is on a waitlist
participatingConsumer is active in a distribution (queued, entered draw, bidding)
admittedConsumer has been admitted through the distribution

Using Journeys for SDK Resume

The SDK uses the journeys array to automatically resume consumer experiences:
// SDK automatically reads journeys from /consumers/me
const { journeys } = await fanfare.consumer.getMe();

// Find the most relevant journey
const activeJourney = journeys.find((j) => j.journeyStage === "admitted");

if (activeJourney?.admission) {
  // Resume checkout flow
  fanfare.checkout.resume(activeJourney.admission);
}

SDK Usage

React

import { useConsumer } from "@fanfare/sdk-react";

function ProfilePage() {
  const { consumer, activeJourneys, isLoading, error } = useConsumer();

  if (isLoading) return <Loading />;
  if (error) return <Error message={error.message} />;

  const admittedJourney = activeJourneys.find(
    (j) => j.journeyStage === "admitted"
  );

  return (
    <div>
      <h1>Welcome, {consumer?.fullName || "Guest"}</h1>
      <p>Email: {consumer?.email}</p>

      {admittedJourney && (
        <div className="alert">
          <p>You have an active admission!</p>
          <a href={`/checkout?token=${admittedJourney.admission?.admissionToken}`}>
            Continue to Checkout
          </a>
        </div>
      )}

      <h2>Your Active Participations</h2>
      {activeJourneys.map((journey) => (
        <JourneyCard key={journey.sequenceId} journey={journey} />
      ))}
    </div>
  );
}

Direct API Usage

async function getConsumerProfile(accessToken: string) {
  const response = await fetch("https://consumer.fanfare.io/api/v1/consumers/me", {
    headers: {
      "X-Publishable-Key": publishableKey,
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (!response.ok) {
    throw new Error("Failed to fetch consumer profile");
  }

  const data = await response.json();

  return {
    consumer: {
      id: data.id,
      email: data.email,
      phone: data.phone,
      fullName: data.fullName,
    },
    active: data.active,
    journeys: data.active.journeys,
  };
}

Server-Side Consumer Lookup

async function lookupConsumer(consumerId: string) {
  const response = await fetch(`https://consumer.fanfare.io/api/v1/consumers/${consumerId}`, {
    headers: {
      Authorization: `Bearer ${process.env.FANFARE_SECRET_KEY}`,
    },
  });

  if (!response.ok) {
    if (response.status === 404) {
      return null;
    }
    throw new Error("Failed to lookup consumer");
  }

  return response.json();
}