# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fuul.xyz/developer-guide/managing-audiences.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.