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

# Audiences

> Every product gets audiences automatically. Pick one and make campaigns and UGC videos for those people.

An audience is a group of people a product is for. Campaigns and UGC videos
are written for one, the same way the app works: first the audience, then the
ads.

The flow takes three calls:

1. **Create a product.** LocalAds reads it and generates its audiences
   automatically. They are saved as soon as they are written; there is
   nothing to approve.
2. **List the product's audiences** and pick one.
3. **Create a campaign or a UGC video** with that audience's `id` as
   `audience_id`.

Audiences are free. Listing them needs `products:read`; adding, editing and
generating them needs `products:update` (`products:delete` to archive).

## Wait for the audiences

A new product generates its audiences once its details are read, usually
within a minute or two. `GET /products/{product_id}` shows how far along it
is:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127 \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "a1516a75-9be5-461a-93af-c1896a0a3127",
  "name": "First Flush Darjeeling Tea",
  "status": "ready",
  "audiences": { "count": 3, "generation_status": "ready" }
}
```

`generation_status` is `generating` while they are being written, then
`ready`. If it reads `failed`, [generate more](#generate-more-audiences).

## List and pick one

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/audiences \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "generation_status": "ready",
  "data": [
    {
      "id": "2b12fc60-a380-49a2-99f9-33f4f15d386c",
      "name": "Anirban, The Heritage Purist",
      "demographic": "Age 35-60, senior professionals in Kolkata, Mumbai and Delhi",
      "motivation": "The finest single-estate spring harvest, never blended or stale",
      "created_at": "2026-09-30T01:36:55.984Z"
    },
    {
      "id": "af9852a2-152c-4cf1-8048-7612ddf111a9",
      "name": "Meera, The Conscious Ritualist",
      "demographic": "Age 25-40, urban professionals who value organic, sustainable living",
      "motivation": "A light, naturally sweet alternative to coffee for the afternoon break",
      "created_at": "2026-09-30T01:36:55.984Z"
    }
  ]
}
```

Every audience listed is saved and ready. Pick any one.

## Make ads for it

Pass the audience's `id` as `audience_id`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url https://makelocalads.com/api/v1/campaigns \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "audience_id": "2b12fc60-a380-49a2-99f9-33f4f15d386c",
    "blueprint_id": "viral-pattern-interrupt",
    "creative_count": 5
  }'
```

`audience_id` is required when creating a guided campaign, video concepts or a
UGC video, so an audience is never skipped by accident. To make something for
everyone on purpose, send `"audience_id": null`. See
[Create a campaign](/ad-campaigns/create-a-campaign) and
[Create a UGC video](/ugc-videos/create-a-ugc-video) for the rest of each
request.

## Add an audience in your own words

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/audiences \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "description": "Corporate buyers sending premium gifts to top clients." }'
```

LocalAds turns the description into a full audience and returns it with
`201 Created`. The `description` is who the audience is, in your words, 3 to
2,000 characters.

## Edit an audience

Describe what should change:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PATCH \
  --url https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/audiences/2b12fc60-a380-49a2-99f9-33f4f15d386c \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "description": "Focus on buyers who gift tea at Diwali." }'
```

## Generate more audiences

Ask for a fresh set at any time. They are saved automatically, like the first
ones:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  --url https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/audiences/recommendations \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

This answers `202 Accepted`. Poll `GET /products/{product_id}/audiences` until
`generation_status` is `ready`.

## Archive an audience

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request DELETE \
  --url https://makelocalads.com/api/v1/products/a1516a75-9be5-461a-93af-c1896a0a3127/audiences/2b12fc60-a380-49a2-99f9-33f4f15d386c \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

This answers `204 No Content`. The audience stops appearing in lists and can
no longer be passed as `audience_id`. Campaigns and videos already made for it
are not affected.