> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Audiences

> Create, replace, read, and delete the stored recipient lists your campaigns send to 📋

## Create or replace an audience

```json theme={null}
POST https://api.connectly.ai/v1/businesses/{businessId}/create/audiences
```

| Parameter    | Location | Description                 |
| ------------ | -------- | --------------------------- |
| `businessId` | Path     | Your Connectly business ID. |
| `X-API-Key`  | Header   | Your API key.               |

Takes the `csvAssetId` returned by [Upload recipients](https://docs.connectly.ai/audiences/upload-recipients), reads the file, and stores the list.

### Request body

| Field             | Type   | Required | Description                                                                                   |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `csvAssetId`      | string | Yes      | Asset id of the uploaded CSV.                                                                 |
| `name`            | string | No       | Display name, also what identifies the audience in the Connectly app. Generated when omitted. |
| `recipientColumn` | string | No       | Header of the column holding the recipient identifier. Defaults to the first column.          |
| `audienceId`      | string | No       | Replace this audience's recipients instead of creating a new one.                             |

```json theme={null}
{
  "name": "black_friday_2026",
  "csvAssetId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "recipientColumn": "phone"
}
```

### Response

```json theme={null}
{
  "data": {
    "audience": {
      "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
      "name": "black_friday_2026",
      "recipientCount": 9998,
      "variables": ["name", "order_id"],
      "createdAt": "2026-11-20T09:14:02.384Z",
      "updatedAt": "2026-11-20T09:14:02.384Z",
      "downloadUrl": "https://..."
    },
    "acceptedCount": 9998,
    "rejectedCount": 2,
    "error": {
      "message": "rejected 2 of 10000 entries: invalid phone number (2)"
    }
  }
}
```

Rows whose recipient cannot be read are dropped and counted in `rejectedCount`, with the reasons in `error`. The request fails only when nothing survives.

<Tip>
  Check `variables` against the campaign you intend to send. These are the column names Connectly stored, and they must match the campaign's placeholders exactly.
</Tip>

### Replacing

Pass `audienceId` to overwrite that audience's recipients with a newly uploaded CSV. The id and any sends already created from it are unchanged.

```json theme={null}
{
  "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
  "csvAssetId": "c81d4e2e-bcf2-11e6-869b-7df92533d2db",
  "recipientColumn": "phone"
}
```

An `audienceId` that names nothing returns `404` — it is not created for you.

***

## Get an audience

```json theme={null}
GET https://api.connectly.ai/v1/businesses/{businessId}/get/audiences/{audienceId}
```

```json theme={null}
{
  "data": {
    "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
    "name": "black_friday_2026",
    "recipientCount": 9998,
    "variables": ["name", "order_id"],
    "createdAt": "2026-11-20T09:14:02.384Z",
    "updatedAt": "2026-11-20T09:14:02.384Z",
    "downloadUrl": "https://..."
  }
}
```

`downloadUrl` is a time-limited link to the stored CSV, valid for **one hour**. Request the audience again for a fresh link. The recipients are never returned inline — a million-recipient list is well over 100MB.

***

## Delete an audience

```json theme={null}
DELETE https://api.connectly.ai/v1/businesses/{businessId}/delete/audiences/{audienceId}
```

Sends already created from the audience are unaffected; each keeps its own copy of the recipients.

***

## Errors

| Status | Cause                                                                                                                                                          |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `csvAssetId` is missing, the CSV has more than 1,000,000 recipients, `recipientColumn` names no column in the file, or no recipient in the file could be read. |
| `404`  | `csvAssetId` or `audienceId` names nothing you own.                                                                                                            |
| `401`  | Missing or invalid API key.                                                                                                                                    |
| `429`  | More than 60 create requests in a minute.                                                                                                                      |

## Next step

<Card title="Send to an audience" icon="paper-plane" href="https://docs.connectly.ai/campaigns/send-to-audience">
  Send a published campaign to the audience, now or on a schedule.
</Card>