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

# Create Audience

> Create a new audience segment with filter conditions.

Creates a new audience with the specified filter definition. The audience size is not calculated at creation time — use the [Get Audience Size](/api-reference/v2/audiences/get-audience-size) endpoint to trigger a size calculation.

## Body Parameters

<ParamField body="name" type="string" required>
  Name of the audience. Maximum 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional description for the audience. Maximum 1000 characters. A longer value currently returns a `500` error rather than a validation error.
</ParamField>

<ParamField body="source_lists" type="array of integers">
  Sending list IDs to scope this audience to. If omitted or empty, the audience will include contacts from all lists.
</ParamField>

<ParamField body="filter" type="object" required>
  Filter group definition. See the [Audience Filter DSL](/api-reference/v2/audience-filter-dsl) reference for the full specification.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  `true` if the audience was created successfully.
</ResponseField>

<ResponseField name="audience" type="object">
  The full audience object.

  <Expandable title="Audience object properties">
    <ResponseField name="id" type="string">
      Unique audience identifier.
    </ResponseField>

    <ResponseField name="name" type="string">
      Audience name.
    </ResponseField>

    <ResponseField name="description" type="string">
      Audience description.
    </ResponseField>

    <ResponseField name="source_lists" type="array of integers">
      Sending list IDs this audience is scoped to.
    </ResponseField>

    <ResponseField name="filter" type="object">
      The filter group definition. Condition objects in responses use camelCase keys (e.g. `conditionType`).
    </ResponseField>

    <ResponseField name="cached_size" type="integer">
      Audience size. `null` until calculated via the [Get Audience Size](/api-reference/v2/audiences/get-audience-size) endpoint.
    </ResponseField>

    <ResponseField name="cached_size_updated_at" type="datetime">
      Timestamp of last size calculation. `null` until calculated.
    </ResponseField>

    <ResponseField name="status" type="string">
      Audience status: `active`.
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the audience was created.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tracklysms.com/api/v2/audiences" \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "California T-Mobile Users",
      "description": "Contacts in CA on T-Mobile who clicked recently",
      "source_lists": [101],
      "filter": {
        "operator": "AND",
        "conditions": [
          {
            "condition_type": "custom_field",
            "field": "state",
            "operator": "eq",
            "value": "CA"
          },
          {
            "condition_type": "carrier",
            "field": "carrier",
            "operator": "eq",
            "value": "T-Mobile"
          },
          {
            "condition_type": "time",
            "field": "last_clicked_at",
            "operator": "within",
            "value": 14,
            "unit": "days"
          }
        ]
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tracklysms.com/api/v2/audiences",
      headers={
          "X-Api-Key": "trk_your_api_key_here",
          "Content-Type": "application/json",
      },
      json={
          "name": "California T-Mobile Users",
          "description": "Contacts in CA on T-Mobile who clicked recently",
          "source_lists": [101],
          "filter": {
              "operator": "AND",
              "conditions": [
                  {
                      "condition_type": "custom_field",
                      "field": "state",
                      "operator": "eq",
                      "value": "CA",
                  },
                  {
                      "condition_type": "carrier",
                      "field": "carrier",
                      "operator": "eq",
                      "value": "T-Mobile",
                  },
                  {
                      "condition_type": "time",
                      "field": "last_clicked_at",
                      "operator": "within",
                      "value": 14,
                      "unit": "days",
                  },
              ],
          },
      },
  )

  data = response.json()
  print(f"Created audience: {data['audience']['id']}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.tracklysms.com/api/v2/audiences", {
    method: "POST",
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "California T-Mobile Users",
      description: "Contacts in CA on T-Mobile who clicked recently",
      source_lists: [101],
      filter: {
        operator: "AND",
        conditions: [
          {
            condition_type: "custom_field",
            field: "state",
            operator: "eq",
            value: "CA",
          },
          {
            condition_type: "carrier",
            field: "carrier",
            operator: "eq",
            value: "T-Mobile",
          },
          {
            condition_type: "time",
            field: "last_clicked_at",
            operator: "within",
            value: 14,
            unit: "days",
          },
        ],
      },
    }),
  });

  const data = await response.json();
  console.log(`Created audience: ${data.audience.id}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 — Created theme={null}
  {
    "success": true,
    "audience": {
      "id": "664f1a2b3c4d5e6f7a8b9c0d",
      "name": "California T-Mobile Users",
      "description": "Contacts in CA on T-Mobile who clicked recently",
      "source_lists": [101],
      "filter": {
        "operator": "AND",
        "conditions": [
          {
            "conditionType": "custom_field",
            "field": "state",
            "operator": "eq",
            "value": "CA",
            "unit": null,
            "listId": null
          },
          {
            "conditionType": "carrier",
            "field": "carrier",
            "operator": "eq",
            "value": "T-Mobile",
            "unit": null,
            "listId": null
          },
          {
            "conditionType": "time",
            "field": "last_clicked_at",
            "operator": "within",
            "value": 14,
            "unit": "days",
            "listId": null
          }
        ],
        "groups": []
      },
      "cached_size": null,
      "cached_size_updated_at": null,
      "status": "active",
      "created_at": "2025-11-20T10:15:00"
    }
  }
  ```

  ```json 400 — Missing Name theme={null}
  {
    "error": "name is required",
    "code": "missing_name"
  }
  ```

  ```json 400 — Invalid Filter theme={null}
  {
    "error": "Invalid condition_type: invalid",
    "code": "invalid_condition_type"
  }
  ```

  ```json 400 — Source List Not Found theme={null}
  {
    "error": "Source list not found: 999",
    "code": "source_list_not_found"
  }
  ```

  ```json 401 — Unauthorized theme={null}
  {
    "error": "Invalid credentials",
    "code": "invalid_credentials"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code                       | Description                                                                           |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------------- |
| 400         | `missing_name`                   | The `name` field was not provided                                                     |
| 400         | `missing_filter`                 | The `filter` field was not provided                                                   |
| 400         | `name_too_long`                  | Name exceeds 255 characters                                                           |
| 400         | `source_list_not_found`          | A sending list ID in `source_lists` does not exist                                    |
| 400         | `invalid_group_operator`         | Filter group `operator` must be `AND` or `OR`                                         |
| 400         | `empty_filter_group`             | Filter group contains no conditions or nested groups                                  |
| 400         | `invalid_condition_type`         | Condition type is not one of the seven valid types                                    |
| 400         | `invalid_time_field`             | Time condition `field` is not valid                                                   |
| 400         | `invalid_time_operator`          | Time condition `operator` is not valid                                                |
| 400         | `invalid_time_unit`              | Time condition `unit` must be `days`, `hours`, or `minutes`                           |
| 400         | `missing_time_value`             | Time condition is missing `value` or `unit`                                           |
| 400         | `invalid_count_field`            | Count condition `field` is not valid                                                  |
| 400         | `invalid_count_operator`         | Count condition `operator` is not valid                                               |
| 400         | `missing_count_value`            | Count condition is missing `value`                                                    |
| 400         | `missing_custom_field_name`      | Custom field condition is missing `field`                                             |
| 400         | `invalid_custom_field_operator`  | Custom field condition `operator` is not valid                                        |
| 400         | `missing_custom_field_value`     | Custom field condition is missing `value` (and operator is not `exists`/`not_exists`) |
| 400         | `invalid_carrier_operator`       | Carrier condition `operator` is not valid                                             |
| 400         | `missing_carrier_value`          | Carrier condition is missing `value` (and operator is not `exists`/`not_exists`)      |
| 400         | `invalid_timezone_operator`      | Timezone condition `operator` is not valid                                            |
| 400         | `missing_timezone_value`         | Timezone condition is missing `value`                                                 |
| 400         | `invalid_revenue_field`          | Revenue condition `field` is not valid                                                |
| 400         | `invalid_revenue_operator`       | Revenue condition `operator` is not valid                                             |
| 400         | `missing_revenue_value`          | Revenue condition is missing `value`                                                  |
| 400         | `invalid_phone_numbers_operator` | Phone numbers condition `operator` is not `in` or `not_in`                            |
| 400         | `missing_phone_numbers_value`    | Phone numbers condition `value` is missing or an empty list                           |
| 401         | `invalid_credentials`            | API key is missing or invalid                                                         |
| 403         | `account_suspended`              | Your account is suspended. Resolve outstanding billing or contact support.            |
| 429         | `rate_limited`                   | Request throttled; retry with exponential backoff after the window resets.            |

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Audiences" icon="users" href="/guides/audiences/creating-audiences">
    Build audiences in the UI
  </Card>

  <Card title="Create Schedule" icon="calendar" href="/api-reference/v2/schedules/create-schedule">
    Schedule a campaign to your audience
  </Card>
</CardGroup>