Consumers API

Consumers represent end users in the Fanfare platform. Use these endpoints to create, manage, and query consumer records.

Create Consumer

Create a new consumer. POST /api/v1/consumers

Authentication

Secret key required

Request Body

interface CreateConsumerRequest {
  email?: string;
  phone?: string; // E.164 format recommended
  fullName?: string;
  metadata?: Record<string, unknown>;
  externalId?: string;
}

Response

interface Consumer {
  id: string;
  email: string | null;
  phone: string | null;
  fullName: string | null;
  metadata: Record<string, unknown> | null;
  externalId: string | null;
  totalOrders: number;
  totalOrderValue: number;
  lastOrderAt: string | null;
  createdAt: string;
  updatedAt: string;
}

Example

curl -X POST https://admin.fanfare.io/api/v1/consumers \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "fullName": "John Doe",
    "metadata": {
      "source": "import",
      "tier": "vip"
    }
  }'

Response:

{
  "id": "cons_01HXYZ123456789",
  "email": "[email protected]",
  "phone": null,
  "fullName": "John Doe",
  "metadata": {
    "source": "import",
    "tier": "vip"
  },
  "externalId": null,
  "totalOrders": 0,
  "totalOrderValue": 0,
  "lastOrderAt": null,
  "createdAt": "2024-11-01T10:00:00Z",
  "updatedAt": "2024-11-01T10:00:00Z"
}

Error Responses

Status	Error	Description
400	`Validation failed`	Invalid request data
400	`Email already exists`	Duplicate email
401	`Authentication required`	Missing authentication

List Consumers

List consumers with pagination, search, and filtering. GET /api/v1/consumers

Authentication

Secret key required

Query Parameters

Parameter	Type	Default	Description
`first`	number	20	Number of items per page (max 100)
`after`	string	-	Cursor for forward pagination
`before`	string	-	Cursor for backward pagination
`last`	number	-	Items for backward pagination
`search`	string	-	Search by email, phone, or name (min 2 chars)
`sortBy`	string	`createdAt`	Field to sort by
`sortDir`	string	`desc`	Sort direction (`asc` or `desc`)
`createdAfter`	string	-	Filter by creation date
`createdBefore`	string	-	Filter by creation date
`audienceId`	string	-	Filter by audience membership
`include`	string	-	Relations to include (`audiences`)

Response

interface ConsumersListResponse {
  data: Consumer[];
  pageInfo: {
    startCursor: string | null;
    endCursor: string | null;
  };
}

Example

curl -X GET "https://admin.fanfare.io/api/v1/consumers?first=20&search=john&sortBy=createdAt&sortDir=desc" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Response:

{
  "data": [
    {
      "id": "cons_01HXYZ123456789",
      "email": "[email protected]",
      "fullName": "John Doe",
      "createdAt": "2024-11-01T10:00:00Z"
    },
    {
      "id": "cons_01HXYZ123456790",
      "email": "[email protected]",
      "fullName": "John Smith",
      "createdAt": "2024-10-15T08:00:00Z"
    }
  ],
  "pageInfo": {
    "startCursor": "eyJpZCI6ImNvbnNfMDFIWFlaIn0=",
    "endCursor": "eyJpZCI6ImNvbnNfMDFIWFlaMn0="
  }
}

Get Consumer

Get a single consumer by ID. GET /api/v1/consumers/:id

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The consumer ID

Query Parameters

Parameter	Type	Description
`include`	string	Relations to include (`audiences`, `orders`)

Example

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

Error Responses

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

Update Consumer

Update an existing consumer. PUT /api/v1/consumers/:id

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The consumer ID

Request Body

interface UpdateConsumerRequest {
  email?: string | null;
  phone?: string | null;
  fullName?: string | null;
  metadata?: Record<string, unknown> | null;
  externalId?: string | null;
}

Example

curl -X PUT https://admin.fanfare.io/api/v1/consumers/cons_01HXYZ123456789 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "John A. Doe",
    "metadata": {
      "tier": "platinum"
    }
  }'

Error Responses

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

Delete Consumer

Delete a consumer. DELETE /api/v1/consumers/:id

Authentication

Secret key required

Path Parameters

Parameter	Type	Description
`id`	string	The consumer ID

Example

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

Response

Returns the deleted consumer.

Batch Create Consumers

Create multiple consumers in a single request. POST /api/v1/consumers/batch

Authentication

Secret key required

Request Body

type BatchCreateConsumersRequest = CreateConsumerRequest[];

Maximum batch size: 500 consumers

Example

curl -X POST https://admin.fanfare.io/api/v1/consumers/batch \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    {"email": "[email protected]", "fullName": "User One"},
    {"email": "[email protected]", "fullName": "User Two"},
    {"email": "[email protected]", "fullName": "User Three"}
  ]'

Response:

[
  {
    "id": "cons_01HXYZ123456789",
    "email": "[email protected]",
    "fullName": "User One"
  },
  {
    "id": "cons_01HXYZ123456790",
    "email": "[email protected]",
    "fullName": "User Two"
  },
  {
    "id": "cons_01HXYZ123456791",
    "email": "[email protected]",
    "fullName": "User Three"
  }
]

Error Responses

Status	Error	Description
400	`Max batch size is 500`	Too many consumers in batch

Batch Update Consumers

Update multiple consumers in a single request. PUT /api/v1/consumers/batch

Authentication

Secret key required

Request Body

interface BatchUpdateConsumerItem extends UpdateConsumerRequest {
  id: string;
}

type BatchUpdateConsumersRequest = BatchUpdateConsumerItem[];

Example

curl -X PUT https://admin.fanfare.io/api/v1/consumers/batch \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    {"id": "cons_01HXYZ123456789", "metadata": {"tier": "gold"}},
    {"id": "cons_01HXYZ123456790", "metadata": {"tier": "silver"}}
  ]'

Search Consumers

Search consumers with additional search options. GET /api/v1/consumers/search

Authentication

Secret key required

Query Parameters

Parameter	Type	Description
`q`	string	Search query (min 2 chars)
`email`	string	Exact email match
`phone`	string	Exact phone match
`externalId`	string	Exact external ID match
`first`	number	Page size

Example

curl -X GET "https://admin.fanfare.io/api/v1/consumers/[email protected]" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Sortable Fields

Field	Description
`createdAt`	Consumer creation date (default)
`email`	Email address (alphabetical)
`fullName`	Full name (alphabetical)
`lastOrderAt`	Most recent order date
`totalOrderValue`	Lifetime order value
`totalOrders`	Total order count

SDK Usage

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

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

// Create consumer
const consumer = await admin.consumers.create({
  email: "[email protected]",
  fullName: "John Doe",
});

// List consumers with pagination
const { data: consumers, pageInfo } = await admin.consumers.list({
  first: 20,
  search: "john",
  sortBy: "createdAt",
  sortDir: "desc",
});

// Get next page
if (pageInfo.endCursor) {
  const nextPage = await admin.consumers.list({
    first: 20,
    after: pageInfo.endCursor,
  });
}

// Update consumer
await admin.consumers.update(consumer.id, {
  metadata: { tier: "vip" },
});

// Batch create
await admin.consumers.batchCreate([{ email: "[email protected]" }, { email: "[email protected]" }]);

// Delete consumer
await admin.consumers.delete(consumer.id);

Overview

Consumer API

Admin API

Webhooks

​Consumers API

​Create Consumer

​Authentication

​Request Body

​Response

​Example

​Error Responses

​List Consumers

​Authentication

​Query Parameters

​Response

​Example

​Get Consumer

​Authentication

​Path Parameters

​Query Parameters

​Example

​Error Responses

​Update Consumer

​Authentication

​Path Parameters

​Request Body

​Example

​Error Responses

​Delete Consumer

​Authentication

​Path Parameters

​Example

​Response

​Batch Create Consumers

​Authentication

​Request Body

​Example

​Error Responses

​Batch Update Consumers

​Authentication

​Request Body

​Example

​Search Consumers

​Authentication

​Query Parameters

​Example

​Sortable Fields

​SDK Usage

Consumers API

Create Consumer

Authentication

Request Body

Response

Example

Error Responses

List Consumers

Authentication

Query Parameters

Response

Example

Get Consumer

Authentication

Path Parameters

Query Parameters

Example

Error Responses

Update Consumer

Authentication

Path Parameters

Request Body

Example

Error Responses

Delete Consumer

Authentication

Path Parameters

Example

Response

Batch Create Consumers

Authentication

Request Body

Example

Error Responses

Batch Update Consumers

Authentication

Request Body

Example

Search Consumers

Authentication

Query Parameters

Example

Sortable Fields

SDK Usage