Skip to main content

​
Organizations API

Organizations represent multi-tenant accounts in the Fanfare platform. These endpoints allow you to manage organization settings and configuration.

​
Get Current Organization

Get the current organization details. GET /api/v1/organizations/current

​
Authentication

  • Secret key required

​
Response

interface Organization {
  id: string;
  name: string;
  slug: string;
  logoUrl: string | null;
  faviconUrl: string | null;
  timeZone: string;
  countryCode: string;
  languageCode: string;
  currencyCode: string;
  status: "ACTIVE" | "INACTIVE" | "PENDING";
  plan: "FREE" | "STARTER" | "GROWTH" | "ENTERPRISE";
  clerkOrganizationId: string;
  createdAt: string;
  updatedAt: string;
}

​
Example

curl -X GET https://admin.fanfare.io/api/v1/organizations/current \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
Response: 
{
  "id": "org_01HXYZ123456789",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "logoUrl": "https://cdn.fanfare.io/orgs/acme/logo.png",
  "faviconUrl": null,
  "timeZone": "America/New_York",
  "countryCode": "US",
  "languageCode": "en",
  "currencyCode": "USD",
  "status": "ACTIVE",
  "plan": "GROWTH",
  "clerkOrganizationId": "org_clerk_123456",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-12-01T15:30:00Z"
}

​
Error Responses

StatusErrorDescription
404Organization not foundOrganization does not exist

​
Update Organization

Update organization details. PUT /api/v1/organizations

​
Authentication

  • Secret key required

​
Request Body

interface UpdateOrganizationRequest {
  name?: string;
  slug?: string;
  logoUrl?: string | null;
  faviconUrl?: string | null;
  timeZone?: string;
  countryCode?: string;
  languageCode?: string;
  currencyCode?: string;
}

​
Example

curl -X PUT https://admin.fanfare.io/api/v1/organizations \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "timeZone": "America/Los_Angeles",
    "currencyCode": "USD"
  }'
Response: 
{
  "id": "org_01HXYZ123456789",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "logoUrl": "https://cdn.fanfare.io/orgs/acme/logo.png",
  "faviconUrl": null,
  "timeZone": "America/Los_Angeles",
  "countryCode": "US",
  "languageCode": "en",
  "currencyCode": "USD",
  "status": "ACTIVE",
  "plan": "GROWTH",
  "clerkOrganizationId": "org_clerk_123456",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-12-01T16:00:00Z"
}

​
Error Responses

StatusErrorDescription
400Slug already takenSlug is used by another org
400Invalid slug formatSlug contains invalid chars
400Validation failedInvalid request data

​
Check Slug Availability

Check if an organization slug is available. GET /api/v1/organizations/slug/availability

​
Authentication

  • Optional (if authenticated, excludes current org from check)

​
Query Parameters

ParameterTypeDescription
slugstringThe slug to check

​
Response

interface SlugAvailabilityResponse {
  slug: string;
  available: boolean;
  reason?: "TAKEN" | "RESERVED" | "INVALID_FORMAT";
}

​
Example

curl -X GET "https://admin.fanfare.io/api/v1/organizations/slug/availability?slug=my-brand" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
Response (available): 
{
  "slug": "my-brand",
  "available": true
}
Response (taken): 
{
  "slug": "acme-corp",
  "available": false,
  "reason": "TAKEN"
}

​
Slug Requirements

Organization slugs must follow these rules:
RuleDescription
Length3-50 characters
CharactersLowercase letters, numbers, hyphens
Start/EndMust start and end with letter or number
No consecutive hyphensCannot contain --
Reserved wordsCannot use reserved system slugs

​
Reserved Slugs

The following slugs are reserved and cannot be used:
  • admin, api, app, auth
  • dashboard, settings, account
  • fanfare, waitify, support
  • www, mail, ftp, cdn

​
Organization Settings

Organization settings are managed through a separate Settings API. Common settings include:

​
Notification Settings

Configure email and SMS notifications: 
interface NotificationSettings {
  email: {
    enabled: boolean;
    fromName: string;
    fromEmail: string;
    replyToEmail?: string;
  };
  sms: {
    enabled: boolean;
    fromNumber?: string;
  };
}

​
Integration Settings

Configure third-party integrations: 
interface IntegrationSettings {
  klaviyo?: {
    apiKey: string;
    publicKey: string;
  };
  shopify?: {
    shopDomain: string;
    accessToken: string;
  };
}
See the Settings API for managing these configurations.

​
Time Zone Support

Fanfare supports all IANA time zones. Common examples:
Time ZoneDescription
America/New_YorkEastern Time (US)
America/Los_AngelesPacific Time (US)
America/ChicagoCentral Time (US)
Europe/LondonBritish Time
Europe/ParisCentral European
Asia/TokyoJapan Standard Time
Australia/SydneyAustralian Eastern
UTCCoordinated UTC
Time zones affect:
  • Scheduled experience open/close times
  • Analytics reporting periods
  • Notification scheduling
  • Dashboard displays

​
Currency Support

Fanfare supports all ISO 4217 currency codes:
CodeCurrency
USDUS Dollar
EUREuro
GBPBritish Pound
CADCanadian Dollar
AUDAustralian Dollar
JPYJapanese Yen
CHFSwiss Franc
Currency settings affect:
  • Product pricing display
  • Order totals and revenue reporting
  • Analytics currency conversions

​
SDK Usage

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

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

// Get current organization
const org = await admin.organizations.getCurrent();
console.log(`Organization: ${org.name} (${org.slug})`);

// Update organization
const updated = await admin.organizations.update({
  name: "Acme Corporation",
  timeZone: "America/Los_Angeles",
});

// Check slug availability
const availability = await admin.organizations.checkSlugAvailability("my-brand");
if (availability.available) {
  await admin.organizations.update({ slug: "my-brand" });
}

​
Multi-Tenancy

Fanfare is a multi-tenant platform where each organization has completely isolated data:
ResourceIsolation Level
ConsumersPer organization
ExperiencesPer organization
ProductsPer organization
OrdersPer organization
AudiencesPer organization
API KeysPer organization
SettingsPer organization
AnalyticsPer organization

​
Organization IDs

All API responses include organizationId to identify the owning organization. This ID is automatically scoped based on your API key.

​
Cross-Organization Access

Cross-organization access is not supported through the API. Each API key is scoped to exactly one organization.