> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/developer-guide/managing-audiences.md).

# 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:

```typescript
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](https://fuul.readme.io/reference/getaudiencesegments)                |
| List all segments    | `GET /v1/audiences/audience-segments`                               | [View](https://fuul.readme.io/reference/get_v1-audiences-audience-segments) |
| Get segment entries  | `GET /v1/audience-segments/{segmentId}/entries`                     | [View](https://fuul.readme.io/reference/getsegmententries)                  |
| Add entries (batch)  | `POST /v1/audience-segments/{segmentId}/entries/batch`              | [View](https://fuul.readme.io/reference/addsegmententriesbatch)             |
| Remove entry         | `DELETE /v1/audience-segments/{segmentId}/entries/{userIdentifier}` | [View](https://fuul.readme.io/reference/removesegmententry)                 |
| Create badge         | `POST /v1/audience-segments/{segmentId}/badge`                      | [View](https://fuul.readme.io/reference/uploadsegmentbadge)                 |
| Update badge         | `PATCH /v1/audience-segments/{segmentId}/badge`                     | [View](https://fuul.readme.io/reference/updatesegmentbadge)                 |
| Delete badge         | `DELETE /v1/audience-segments/{segmentId}/badge`                    | [View](https://fuul.readme.io/reference/deletesegmentbadge)                 |

### Example: add users to an audience

```bash
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" }
    ]
  }'
```

{% hint style="info" %}
A **service\_role** API key is required for audience management endpoints.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}