Experiences API

Experiences are the top-level containers for distribution flows. Each experience can contain multiple sequences with different distribution types.

Create Experience

Create a new experience. POST /api/v1/experiences

Authentication

Secret key required

Request Body

interface CreateExperienceRequest {
  name: string;
  slug?: string;
  openAt?: string; // ISO 8601 timestamp
  closeAt?: string; // ISO 8601 timestamp
  timeZone?: string;
  i18n?: ExperienceI18n;
  theme?: ExperienceTheme;
}

Response

interface Experience {
  id: string;
  name: string;
  slug: string;
  openAt: string | null;
  closeAt: string | null;
  timeZone: string | null;
  i18n: ExperienceI18n | null;
  theme: ExperienceTheme | null;
  status: "draft" | "scheduled" | "active" | "completed";
  createdAt: string;
  updatedAt: string;
  createdBy: string;
  updatedBy: string;
}

Example

curl -X POST https://admin.fanfare.io/api/v1/experiences \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Holiday Sale",
    "slug": "holiday-sale-2024",
    "openAt": "2024-12-01T09:00:00Z",
    "closeAt": "2024-12-01T18:00:00Z",
    "timeZone": "America/New_York"
  }'

Response:

{
  "id": "exp_01HXYZ123456789",
  "name": "Holiday Sale",
  "slug": "holiday-sale-2024",
  "openAt": "2024-12-01T09:00:00Z",
  "closeAt": "2024-12-01T18:00:00Z",
  "timeZone": "America/New_York",
  "i18n": null,
  "theme": null,
  "status": "scheduled",
  "createdAt": "2024-11-01T10:00:00Z",
  "updatedAt": "2024-11-01T10:00:00Z",
  "createdBy": "user_01HXYZ123456789",
  "updatedBy": "user_01HXYZ123456789"
}

Error Responses

Status	Error	Description
400	`Validation failed`	Invalid request data
401	`Authentication required`	Missing or invalid authentication

List Experiences

List all experiences for the organization. GET /api/v1/experiences

Authentication

Secret key required

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated relations to include (`sequences`, `distributions`)

Response

Returns an array of Experience objects.

Example

curl -X GET "https://admin.fanfare.io/api/v1/experiences?include=sequences" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Response:

[
  {
    "id": "exp_01HXYZ123456789",
    "name": "Holiday Sale",
    "slug": "holiday-sale-2024",
    "openAt": "2024-12-01T09:00:00Z",
    "closeAt": "2024-12-01T18:00:00Z",
    "status": "scheduled",
    "sequences": [
      {
        "id": "seq_01HXYZ123456789",
        "name": "Main Queue",
        "priority": 1
      }
    ]
  },
  {
    "id": "exp_01HXYZ987654321",
    "name": "VIP Early Access",
    "slug": "vip-early-access",
    "openAt": "2024-12-01T08:00:00Z",
    "status": "draft"
  }
]

Get Experience

Get a single experience by ID. GET /api/v1/experiences/:id

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The experience ID

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated relations to include

Example

curl -X GET "https://admin.fanfare.io/api/v1/experiences/exp_01HXYZ123456789?include=sequences,metrics" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Error Responses

Status	Error	Description
404	`Experience not found`	Experience ID does not exist

Update Experience

Update an existing experience. PUT /api/v1/experiences/:id

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The experience ID

Request Body

interface UpdateExperienceRequest {
  name?: string;
  slug?: string;
  openAt?: string | null;
  closeAt?: string | null;
  timeZone?: string | null;
  i18n?: ExperienceI18n | null;
  theme?: ExperienceTheme | null;
}

Example

curl -X PUT https://admin.fanfare.io/api/v1/experiences/exp_01HXYZ123456789 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Holiday Sale 2024",
    "openAt": "2024-12-01T10:00:00Z"
  }'

Error Responses

Status	Error	Description
400	`Validation failed`	Invalid request data
404	`Experience not found`	Experience ID does not exist

Delete Experience

Delete an experience. DELETE /api/v1/experiences/:id

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The experience ID

Example

curl -X DELETE https://admin.fanfare.io/api/v1/experiences/exp_01HXYZ123456789 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Response

Returns the deleted experience.

Error Responses

Status	Error	Description
404	`Experience not found`	Experience ID does not exist
409	`Cannot delete active experience`	Experience has active consumers

Duplicate Experience

Create a copy of an experience with all its sequences and distributions. POST /api/v1/experiences/:id/duplicate

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The experience ID to duplicate

Request Body

interface DuplicateExperienceRequest {
  name?: string; // New name (defaults to "Copy of {original name}")
}

Example

curl -X POST https://admin.fanfare.io/api/v1/experiences/exp_01HXYZ123456789/duplicate \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Holiday Sale 2025"
  }'

Experience Theme

The theme object controls visual appearance:

interface ExperienceTheme {
  primaryColor?: string; // Hex color, e.g., "#4F46E5"
  secondaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  logoUrl?: string; // URL to logo image
  headerImageUrl?: string; // URL to header image
  fontFamily?: string;
}

Example Theme

{
  "theme": {
    "primaryColor": "#4F46E5",
    "secondaryColor": "#818CF8",
    "backgroundColor": "#FFFFFF",
    "textColor": "#1F2937",
    "logoUrl": "https://cdn.example.com/logo.png",
    "fontFamily": "Inter"
  }
}

Experience I18n

Internationalization settings:

interface ExperienceI18n {
  title?: Record<string, string>;
  description?: Record<string, string>;
  messages?: Record<string, Record<string, string>>;
}

Example I18n

{
  "i18n": {
    "title": {
      "en": "Holiday Sale",
      "es": "Venta de Navidad",
      "fr": "Vente de Noel"
    },
    "description": {
      "en": "Join our exclusive holiday sale queue",
      "es": "Unase a nuestra cola exclusiva de venta navideña"
    },
    "messages": {
      "waiting": {
        "en": "Please wait while we process your entry...",
        "es": "Por favor espere mientras procesamos su entrada..."
      }
    }
  }
}

Experience Status

Status	Description
`draft`	Experience created but not scheduled
`scheduled`	Experience has future open date
`active`	Experience is currently open
`completed`	Experience has closed

SDK Usage

import { FanfareAdmin } from "@fanfare/admin-sdk";

const admin = new FanfareAdmin({
  secretKey: process.env.FANFARE_SECRET_KEY,
});

// Create experience
const experience = await admin.experiences.create({
  name: "Holiday Sale",
  openAt: "2024-12-01T09:00:00Z",
  closeAt: "2024-12-01T18:00:00Z",
  theme: {
    primaryColor: "#4F46E5",
  },
});

// List experiences
const experiences = await admin.experiences.list({
  include: ["sequences"],
});

// Update experience
await admin.experiences.update(experience.id, {
  name: "Holiday Sale 2024",
});

// Duplicate experience
const copy = await admin.experiences.duplicate(experience.id, {
  name: "Holiday Sale 2025",
});

// Delete experience
await admin.experiences.delete(experience.id);

Overview

Consumer API

Admin API

Webhooks

Documentation Index

​Experiences API

​Create Experience

​Authentication

​Request Body

​Response

​Example

​Error Responses

​List Experiences

​Authentication

​Query Parameters

​Response

​Example

​Get Experience

​Authentication

​Path Parameters

​Query Parameters

​Example

​Error Responses

​Update Experience

​Authentication

​Path Parameters

​Request Body

​Example

​Error Responses

​Delete Experience

​Authentication

​Path Parameters

​Example

​Response

​Error Responses

​Duplicate Experience

​Authentication

​Path Parameters

​Request Body

​Example

​Experience Theme

​Example Theme

​Experience I18n

​Example I18n

​Experience Status

​SDK Usage

Experiences API

Create Experience

Authentication

Request Body

Response

Example

Error Responses

List Experiences

Authentication

Query Parameters

Response

Example

Get Experience

Authentication

Path Parameters

Query Parameters

Example

Error Responses

Update Experience

Authentication

Path Parameters

Request Body

Example

Error Responses

Delete Experience

Authentication

Path Parameters

Example

Response

Error Responses

Duplicate Experience

Authentication

Path Parameters

Request Body

Example

Experience Theme

Example Theme

Experience I18n

Example I18n

Experience Status

SDK Usage