📢Managing Audiences

Programs can set audiences for different tier payouts or allowlists. Each audience can have entries that are:

Type	Description
Static	Entered manually or via API
Dynamic	Users that matched a specific condition automatically

Getting user audiences

Use getUserAudiences to check which audiences a user belongs to:

import { Fuul } from '@fuul/sdk';

await Fuul.getUserAudiences({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
});

Updating audiences via API

Audience write operations (add, remove, batch, badges) are HTTP-only. The SDK exposes getUserAudiences only; all other audience management is done via the Fuul API:

Action	API endpoint	Reference
Get user's audiences	GET /v1/audiences/audience-segments/user	View
List all segments	GET /v1/audiences/audience-segments	View
Get segment entries	GET /v1/audience-segments/{segmentId}/entries	View
Add entries (batch)	POST /v1/audience-segments/{segmentId}/entries/batch	View
Remove entry	DELETE /v1/audience-segments/{segmentId}/entries/{userIdentifier}	View
Create badge	POST /v1/audience-segments/{segmentId}/badge	View
Update badge	PATCH /v1/audience-segments/{segmentId}/badge	View
Delete badge	DELETE /v1/audience-segments/{segmentId}/badge	View

Example: add users to an audience

curl -X POST https://api.fuul.xyz/api/v1/audience-segments/{segmentId}/entries/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-service-role-key" \
  -d '{
    "entries": [
      { "identifier": "0x1234...", "identifier_type": "evm_address" },
      { "identifier": "0x5678...", "identifier_type": "evm_address" }
    ]
  }'

A service_role API key is required for audience management endpoints.

Dashboard add-entry behavior: The dashboard uses a dedicated endpoint (POST /api/v1/projects/:projectId/audiences/:audienceId/entries) that returns 409 Conflict when the user is already in the audience. This prevents silent duplicates. The public batch endpoint (POST /api/v1/audience-segments/:audienceId/entries/batch) keeps its upsert/dedup semantics — duplicates are silently skipped, which is the expected behavior for programmatic bulk imports.