Skip to main content

​
API Overview

The Fanfare API provides programmatic access to the Fanfare platform, enabling you to build integrations for virtual waiting rooms, queues, auctions, draws, and appointment scheduling.

​
Architecture

Fanfare exposes two primary APIs:
APIPurposeBase URL
Consumer APIEnd-user facing operations (joining queues, placing bids, checking status)https://consumer.fanfare.io/api/v1
Admin APIManagement operations (creating experiences, managing audiences, analytics)https://admin.fanfare.io/api/v1
Both APIs follow REST conventions and return JSON responses.

​
API Versioning

The current API version is v1. The version is included in the URL path: 
https://consumer.fanfare.io/api/v1/experiences/{experienceId}
https://admin.fanfare.io/api/v1/experiences

​
Version Lifecycle

  • Current: v1 - Full support, actively maintained
  • Deprecated: Versions are deprecated with 12 months notice before removal
  • Sunset: Deprecated versions are eventually removed

​
Request Format

​
Headers

All API requests should include: 
Content-Type: application/json
Authorization: Bearer {access_token}
For Consumer API with publishable key: 
X-Publishable-Key: pk_live_xxxxxxxxxxxx
For Admin API or Consumer API server-side calls: 
Authorization: Bearer {secret_key}

​
Request Body

Request bodies should be JSON-encoded: 
{
  "name": "Holiday Sale Queue",
  "capacity": 1000,
  "openAt": "2024-12-01T09:00:00Z"
}

​
Response Format

​
Success Responses

Successful responses return the appropriate HTTP status code with a JSON body: 
{
  "id": "exp_01HXYZ123456789",
  "name": "Holiday Sale Queue",
  "capacity": 1000,
  "openAt": "2024-12-01T09:00:00Z",
  "createdAt": "2024-11-01T10:00:00Z",
  "updatedAt": "2024-11-01T10:00:00Z"
}

​
List Responses

List endpoints return arrays, often with pagination metadata: 
{
  "data": [
    { "id": "exp_01HXYZ123456789", "name": "Holiday Sale Queue" },
    { "id": "exp_01HXYZ987654321", "name": "VIP Early Access" }
  ],
  "pageInfo": {
    "startCursor": "eyJpZCI6ImV4cF8wMUhYWVoxMjM0NTY3ODkifQ==",
    "endCursor": "eyJpZCI6ImV4cF8wMUhYWVo5ODc2NTQzMjEifQ=="
  }
}

​
Error Responses

Errors return appropriate HTTP status codes with error details: 
{
  "error": "Validation failed",
  "details": [
    {
      "field": "capacity",
      "message": "Must be a positive integer"
    }
  ]
}

​
HTTP Status Codes

CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
204No Content - Request completed, no response body
400Bad Request - Invalid request parameters
401Unauthorized - Missing or invalid authentication
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
409Conflict - Resource state conflict
423Locked - Resource not yet available (e.g., queue not open)
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side error

​
Multi-Tenancy

Fanfare is a multi-tenant platform. All API requests are scoped to your organization based on your API credentials. You cannot access resources belonging to other organizations.

​
Timestamps

All timestamps in the API are in ISO 8601 format with UTC timezone: 
2024-12-01T09:00:00Z
When creating or updating resources with timestamps, you can specify any valid timezone, but responses will always return UTC.

​
IDs

Fanfare uses UUIDv7 identifiers for all resources. These IDs are:
  • Globally unique
  • Time-ordered (lexicographically sortable)
  • URL-safe
Example: 01HXYZ123456789ABCDEFGHIJ

​
SDKs

Official SDKs are available for common platforms:
  • JavaScript/TypeScript: @fanfare/sdk-core, @fanfare/sdk-react
  • SolidJS: @fanfare/sdk-solid
Install via npm: 
npm install @fanfare/sdk-react

​
Next Steps