Skip to main content

​
Admin API Overview

The Admin API provides programmatic access to manage your Fanfare organization, including experiences, audiences, consumers, products, and analytics.

​
Base URL

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

​
Authentication

All Admin API requests require your secret key: 
Authorization: Bearer sk_live_xxxxxxxxxxxx
Secret keys provide full access to your organization’s resources. Keep them secure and never expose them in client-side code.

​
API Endpoints

​
Experiences

MethodEndpointDescription
POST/experiencesCreate an experience
GET/experiencesList experiences
GET/experiences/:idGet an experience
PUT/experiences/:idUpdate an experience
DELETE/experiences/:idDelete an experience
POST/experiences/:id/duplicateDuplicate an experience

​
Sequences

MethodEndpointDescription
POST/sequencesCreate a sequence
GET/sequencesList sequences
GET/sequences/:idGet a sequence
PUT/sequences/:idUpdate a sequence
DELETE/sequences/:idDelete a sequence
GET/sequences/:id/metricsGet sequence metrics
GET/sequences/:id/waitlist/consumersGet waitlist consumers
POST/sequences/:id/waitlist/enterEnter waitlist

​
Queues

MethodEndpointDescription
POST/queuesCreate a queue
GET/queuesList queues
GET/queues/:idGet a queue
PUT/queues/:idUpdate a queue
DELETE/queues/:idDelete a queue

​
Draws

MethodEndpointDescription
POST/drawsCreate a draw
GET/drawsList draws
GET/draws/:idGet a draw
PUT/draws/:idUpdate a draw
DELETE/draws/:idDelete a draw

​
Auctions

MethodEndpointDescription
POST/auctionsCreate an auction
GET/auctionsList auctions
GET/auctions/:idGet an auction
PUT/auctions/:idUpdate an auction
DELETE/auctions/:idDelete an auction

​
Audiences

MethodEndpointDescription
POST/audiencesCreate an audience
GET/audiencesList audiences
GET/audiences/:idGet an audience
PUT/audiences/:idUpdate an audience
DELETE/audiences/:idDelete an audience
POST/audiences/:id/membersAdd members
DELETE/audiences/:id/membersRemove members

​
Consumers

MethodEndpointDescription
POST/consumersCreate a consumer
GET/consumersList consumers (paginated)
GET/consumers/:idGet a consumer
PUT/consumers/:idUpdate a consumer
DELETE/consumers/:idDelete a consumer
POST/consumers/batchBatch create consumers
PUT/consumers/batchBatch update consumers

​
Products

MethodEndpointDescription
POST/productsCreate a product
GET/productsList products
GET/products/:idGet a product
PUT/products/:idUpdate a product
DELETE/products/:idDelete a product
POST/products/batchBatch create/update products

​
Distributions

MethodEndpointDescription
GET/distributionsList all distributions
GET/distributions/:idGet a distribution
GET/distributions/:id/consumersGet distribution consumers

​
Analytics

MethodEndpointDescription
POST/analytics/queryExecute analytics query

​
Organizations

MethodEndpointDescription
GET/organizations/meGet current organization
PUT/organizations/meUpdate organization
GET/organizations/me/usersGet organization users

​
Settings

MethodEndpointDescription
GET/settingsGet organization settings
PUT/settingsUpdate organization settings

​
Orders

MethodEndpointDescription
POST/ordersCreate an order
POST/orders/batchBatch create orders
GET/ordersList orders
GET/orders/:idGet an order
PUT/orders/:idUpdate an order
DELETE/orders/:idDelete an order

​
Sync Sources

MethodEndpointDescription
POST/sync-sourcesCreate a sync source
GET/sync-sources/searchSearch sync sources
GET/sync-sources/:idGet a sync source
PUT/sync-sources/:idUpdate a sync source
DELETE/sync-sources/:idDelete a sync source

​
Common Patterns

​
Pagination

List endpoints support cursor-based pagination: 
GET /api/v1/consumers?first=20&after=eyJpZCI6ImNvbnNfMDFIWFlaIn0=
See Pagination for details.

​
Filtering

Many list endpoints support filtering via query parameters: 
GET /api/v1/consumers?search=john&createdAfter=2024-01-01

​
Include Relations

Use the include parameter to include related data: 
GET /api/v1/experiences?include=sequences,distributions

​
Sorting

Use sortBy and sortDir parameters: 
GET /api/v1/consumers?sortBy=createdAt&sortDir=desc

​
Rate Limits

Admin API rate limits:
Endpoint CategoryLimitWindow
Read operations1000/min1 minute
Write operations500/min1 minute
Batch operations100/min1 minute
Analytics queries100/min1 minute

​
Response Format

​
Single Resource

{
  "id": "exp_01HXYZ123456789",
  "name": "Holiday Sale",
  "createdAt": "2024-11-01T10:00:00Z",
  "updatedAt": "2024-11-01T10:00:00Z"
}

​
List Response

{
  "data": [...],
  "pageInfo": {
    "startCursor": "...",
    "endCursor": "..."
  }
}

​
Error Response

{
  "error": "Validation failed",
  "details": [
    {
      "field": "name",
      "message": "Required"
    }
  ]
}

​
SDK Usage

​
JavaScript/TypeScript

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

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

// Create an experience
const experience = await admin.experiences.create({
  name: "Holiday Sale",
  openAt: "2024-12-01T09:00:00Z",
});

// List consumers
const consumers = await admin.consumers.list({
  first: 20,
  search: "john",
});

​
Direct API

async function createExperience(data: CreateExperienceInput) {
  const response = await fetch("https://admin.fanfare.io/api/v1/experiences", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FANFARE_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

​
Next Steps