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

# Update Audience

> Rename or describe an existing audience, or soft-delete it by passing status: 2.

Use this endpoint to **rename or describe an existing audience, or soft-delete it**.

## Endpoint

**POST** `/audience/update`

**Content-Type:** `application/json`
**Authentication:** Required (workspace auth)

## Request Body

### Rename / describe

```json theme={null}
{
  "audience_id": 55,
  "audience_name": "VIP Customers 2026",
  "description": "Updated description"
}
```

### Soft-delete

```json theme={null}
{
  "audience_id": 55,
  "status": 2
}
```

| Field           | Type   | Required | Description                                                                                  |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `audience_id`   | number | Yes      | ID of the audience to update                                                                 |
| `audience_name` | string | No       | New name. Must be unique within the workspace. Ignored when `status` is `2`.                 |
| `description`   | string | No       | New description                                                                              |
| `status`        | number | No       | Set to `2` to soft-delete the audience. See [Audience Status Codes](#audience-status-codes). |

## Audience Status Codes

| Code | Status   |
| ---- | -------- |
| `0`  | Inactive |
| `1`  | Active   |
| `2`  | Deleted  |

## Response

```json theme={null}
{
  "message": "Audience updated successfully",
  "data": { "id": 55 }
}
```

When `status: 2` is passed:

```json theme={null}
{
  "message": "Audience deleted successfully",
  "data": { "id": 55 }
}
```

## Error Cases

| Error                                            | Cause                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `Audience Id is missing.`                        | `audience_id` not provided                                                            |
| `Audience not found`                             | `audience_id` doesn't belong to the caller's company/workspace, or is already deleted |
| `Audience name already exists in this workspace` | `audience_name` clashes with another (non-deleted) audience in the workspace          |

## Example cURL

```bash theme={null}
curl -X POST https://www.tryunleashx.com/api/v1/global/audience/update \
  -H "Content-Type: application/json" \
  -H "token: <api_key>" \
  -d '{
    "audience_id": 55,
    "audience_name": "VIP Customers 2026"
  }'
```


## OpenAPI

````yaml api-reference/openapi.json POST /audience/update
openapi: 3.1.0
info:
  title: >-
    UnleashX - Build human like conversations | Voice Agents | Automations | AI
    Workforce
  version: 1.0.0
  description: UnleashX - Your home for human like conversations
servers:
  - url: https://www.tryunleashx.com/api/v1/global/
security:
  - bearerAuth: []
paths:
  /audience/update:
    post:
      tags:
        - Audience
      summary: Update audience
      description: >-
        Rename or describe an existing audience, or soft-delete it by passing
        status: 2.
      parameters:
        - name: token
          in: header
          required: true
          description: API token for authentication
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - audience_id
              properties:
                audience_id:
                  type: integer
                  description: ID of the audience to update
                audience_name:
                  type: string
                  description: >-
                    New name. Must be unique within the workspace. Ignored when
                    status is 2.
                description:
                  type: string
                  description: New description
                status:
                  type: integer
                  enum:
                    - 0
                    - 1
                    - 2
                  description: >-
                    Set to 2 to soft-delete the audience. 0=Inactive, 1=Active,
                    2=Deleted.
      responses:
        '200':
          description: Audience updated or deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
        '400':
          description: >-
            Audience Id is missing. / Audience name already exists in this
            workspace
        '401':
          description: Unauthorized
        '404':
          description: Audience not found
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````