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

# Download Audience Template

> Download a blank Excel (.xlsx) template whose columns are derived from an agent's metadata input fields, an existing audience's saved input variables, or explicitly chosen input-variable IDs. mobile_no must be among the resolved columns.

Use this endpoint to **download a blank Excel template** whose columns match an agent's, an existing audience's, or a chosen set of input variables — ready to fill in and upload via [Create Audience](/api-reference/audience/create-audience).

## Endpoint

**GET** `/audience/download-template`

**Authentication:** Required (workspace auth)

## Query Parameters

| Parameter       | Type            | Required | Description                                                                                                                                                       |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`      | number          | No       | Derive columns from this agent's configured metadata input fields. `mobile_no` is force-added as the first column if the agent's fields don't already include it. |
| `audience_id`   | number          | No       | Derive columns from an existing audience's saved input variables.                                                                                                 |
| `variable_id`   | number \| array | No       | Input-variable registry ID(s) to use as columns, in the order given. Accepts **multiple** IDs — see below. Also accepted as `variable_ids`.                       |
| `audience_name` | string          | No       | Overrides the downloaded file's base name. Defaults to the audience's name (`audience_id` mode) or `audience_template`.                                           |

Only one source is used to resolve columns — `agent_id` is checked first, then `audience_id`, then `variable_id`/`variable_ids`.

### Passing multiple `variable_id`s

Any of these forms work — the resulting columns follow the order the IDs were given in:

* Repeat the param: `?variable_id=12&variable_id=15`
* Comma-separated string: `?variable_id=12,15`
* JSON-encoded array: `?variable_id=%5B12%2C15%5D` (i.e. `[12,15]`, URL-encoded)

## Response

Returns a downloadable **Excel file** (`.xlsx`).

* **Content-Type:** `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
* **Filename:** `<audience_name>.xlsx` (sanitized; falls back to `audience_template.xlsx`)

### Template Columns

One column per resolved variable key, in the order resolved. `mobile_no` must be among them (see Error Cases).

## Behavior

* Duplicate keys (case-insensitive) are removed while preserving the first occurrence's order.
* When using `variable_id`/`variable_ids`, only variables owned by the caller's workspace or global System variables resolve; unmatched IDs are silently dropped.

## Error Cases

| Error                                                           | Cause                                                                                                              |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Audience not found`                                            | `audience_id` doesn't belong to the caller's company/workspace, or is deleted                                      |
| `mobile_no is required — please include the mobile_no variable` | The resolved column set (via `audience_id` or `variable_id`/`variable_ids`) doesn't include a `mobile_no` variable |

## Example cURL

### From an existing audience

```bash theme={null}
curl -X GET "https://www.tryunleashx.com/api/v1/global/audience/download-template?audience_id=55" \
  -H "token: <api_key>" \
  --output audience_template.xlsx
```

### From multiple chosen input variables

```bash theme={null}
curl -X GET "https://www.tryunleashx.com/api/v1/global/audience/download-template?variable_id=12&variable_id=15" \
  -H "token: <api_key>" \
  --output audience_template.xlsx
```


## OpenAPI

````yaml api-reference/openapi.json GET /audience/download-template
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/download-template:
    get:
      tags:
        - Audience
      summary: Download audience template
      description: >-
        Download a blank Excel (.xlsx) template whose columns are derived from
        an agent's metadata input fields, an existing audience's saved input
        variables, or explicitly chosen input-variable IDs. mobile_no must be
        among the resolved columns.
      parameters:
        - name: token
          in: header
          required: true
          description: API token for authentication
          schema:
            type: string
        - name: agent_id
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Derive columns from this agent's configured metadata input fields.
            mobile_no is force-added first if missing. Checked before
            audience_id and variable_id.
        - name: audience_id
          in: query
          required: false
          schema:
            type: integer
          description: Derive columns from an existing audience's saved input variables.
        - name: variable_id
          in: query
          required: false
          schema:
            oneOf:
              - type: integer
              - type: array
                items:
                  type: integer
          description: >-
            Input-variable registry ID(s) to use as columns, in the order given.
            Pass multiple by repeating the param (variable_id=12&variable_id=15)
            or as a comma-separated string (variable_id=12,15). Also accepted as
            variable_ids.
          style: form
          explode: true
          example:
            - 12
            - 15
        - name: audience_name
          in: query
          required: false
          schema:
            type: string
          description: >-
            Overrides the downloaded file's base name. Defaults to the
            audience's name (audience_id mode) or audience_template.
      responses:
        '200':
          description: Excel file download
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          description: mobile_no is required — please include the mobile_no variable
        '401':
          description: Unauthorized
        '404':
          description: Audience not found
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````