# Quickstart


Build an audience of people who visited a brand, check what it holds, then
deliver it to an endpoint connection, with ids carried from one command to the
next.

## Prerequisites

The CLI installed and logged in: see
[Getting Started](/cli/getting-started).

An endpoint connection configured in the console. It links your company to the
partner that receives the data and holds that partner's stored credentials.
Creating one is a console task, not a CLI one.

The examples use bash or zsh syntax, and some pipe `--json` output through
`jq`, which is installed separately. On Windows, run them in Git Bash, or in
WSL with the Linux build installed inside WSL (Homebrew, npm, or the linux
archive).

## 1. Read the catalogs

Every value an audience needs comes from a reference read. They are plain
GETs with no side effects, so they are safe to explore:

```bash
intuizi reference common dataset-types
intuizi reference poi brands --search coffee
```

Every catalog except `profile-attributes recency-limits` takes `--search`, a
case-insensitive contains match, so `coffee` finds every brand whose label
contains it. [Catalogs](/cli/reference/catalogs) says which field each catalog
matches. The POI catalogs cascade, so
segments narrow categories, categories narrow brands, and brands narrow
locations:

```bash
intuizi reference poi segments
intuizi reference poi categories --segments <segment_id>
intuizi reference poi brands --categories <category_id>
```

Geography cascades too, countries down to zipcodes, but there each level
requires its parent. See [Catalogs](/cli/reference/catalogs#cascading-reads)
and [Working with Reference Data](/guides/working-with-reference-data).

## 2. Build it

```bash
id=$(intuizi audiences create \
  --type poi --brand "Example Coffee" \
  --country USA \
  --start-date 2026-09-02 --end-date 2026-09-09 \
  --name "Coffee lovers - 1 week" \
  --wait --quiet)
```

Four things are happening in that command.

`--brand "Example Coffee"` is a name, not an id. The CLI looks it up in the
brands catalog with the same contains match as `--search`, so it also matches
a label such as `Example Coffee Reserve`. When exactly one entry comes back, it
is taken whatever its label, so if `Example Coffee Reserve` is the only match,
that brand is built. When several come back and exactly one is labeled
`Example Coffee`, ignoring case, that one is taken. Otherwise the command
fails: no match says so, and several matches are listed with their ids. To see
which id a name resolves to before anything is built, run the `--dry-run` form
below: the id is in `analysisdata`. Pass the id from step 1 instead of the name
to skip the lookup.

`--provider` is absent, which includes every signal provider for the dataset
type, and that is almost always what you want. A `--provider` the type's
catalog does not list is rejected before anything is created, since the CLI
checks it against the catalog it reads.

`--wait` polls until the build reaches Completed or fails, printing each
status change to stderr as it happens. It times out after `--timeout`, 60
minutes by default, and gives up after three failed reads in a row, for
example during a short API outage. Neither stops the build, which carries on
without it: `intuizi audiences show "$id" --wait` picks it up again.

`--quiet` prints the new id and nothing else, which is what the next command
consumes. It prints the id whatever the outcome, so the exit status is what
says the build completed: `0` once it reads Completed, `1` if the build failed
or the wait timed out or gave up. Check it with `echo $?` before going on, and
read stderr, which says which. Only a failed build is final, such as one that
stopped on `107` Additional Info, whose reason the Audience Manager shows. On a
timeout or a give-up, resume the wait rather than creating the audience again,
which would start a second build that also counts against the
[build budget](/concepts/limits#build-budget).

To see the request body those flags produce without creating anything, swap
`--wait --quiet` for `--dry-run`, which cannot be combined with `--wait`. It
still resolves the brand name and reads the signal-provider catalog, so it
needs a login. Saved to a file, the body is a starting point for the `--file`
form:

```bash
intuizi audiences create \
  --type poi --brand "Example Coffee" \
  --country USA \
  --start-date 2026-09-02 --end-date 2026-09-09 \
  --name "Coffee lovers - 1 week" \
  --dry-run > audience.json
```

The `--file` form is how the nested cases are built: two datasets combined with
an operator, and the refine, crossvisitation, and cross purchase blocks. See
[Create an Audience](/guides/create-an-audience).

To size an audience before building it, run the same command line as
`intuizi audiences estimate create`. It runs the same build without creating
the audience, and with `--wait` prints how many devices it would hold. It
takes as long as a build and counts toward the same limits, so it pays off on
an audience you are unsure of rather than on every one. See
[Estimate create](/cli/reference/audiences#estimate-create).

## 3. Check it

Read the audience back before paying to deliver it:

```bash
intuizi audiences show "$id" --json \
  | jq '.data[0] | {results_count, is_activation_allowed, eligibility, normalized_payload}'
```

`results_count` is how many devices the audience holds, and an implausible
count is the first sign that a filter is wrong. `is_activation_allowed` is the
audience-level verdict of the eligibility gates, including the minimum device
count in [Limits & Quotas](/concepts/limits). When it is `false`,
`eligibility.reasons` says why, and the activation in step 4 would be refused.
A `true` can still carry `eligibility.notices`: each lists in
`blocks_identifiers` the identifiers it blocks, and step 4 is refused if its
pricing model delivers one of them. See [Get Audience](/api/v2/audiences#get-apiv2analysesaudiencesid).

`normalized_payload` is the canonical copy of the `name`, `operator`, and
`datasets` the audience was created from. `recipe_hash` is computed from its
`operator` and `datasets` only, so the name does not change it. A per-dataset filter, such as the brand or the country, that is missing
from it was not sent. The top-level `crossvisitation`, `crosspurchase`, and
`analyses` blocks are never part of it, even when they were applied.

## 4. Deliver it

An activation names an endpoint connection, a pricing model, and the
datastreams to deliver. Start with the connection, and read it with `--json`,
because the table shows its nested partner as `{...}`:

```bash
intuizi reference common endpoint-connections --json \
  | jq '.data[] | {id, name, partner_id: .partner.id, inputs: .partner.inputs}'
```

Keep the `id` of the connection to deliver to and its `partner_id`. Its
`inputs` come up again below. Pricing
models and datastreams are read per partner, using that connection's own
partner. A pricing model from any other partner is refused.

```bash
intuizi reference common pricing-models --partner-id <partner_id>
intuizi reference common datastreams --partner-id <partner_id> --json \
  | jq '.data[] | {id, name, dataset_types}'
```

A datastream is one of the partner's delivery outputs. Pick one whose
`dataset_types` include `poi`, the type this audience was built from, since a
stream that applies to none of the audience's types is refused. Then activate:

```bash
intuizi activations create \
  --audience-id "$id" \
  --endpoint-connection-id <connection_id> \
  --pricing-model-id <pricing_model_id> \
  --datastream <datastream_id> \
  --wait
```

Repeat `--datastream` for more than one. Without it, the activation completes
and delivers nothing, and the command warns on stderr. `--wait` follows the
export through `105` DataStreaming to `104` Completed, and exits non-zero if
the export stops, as on `107` Additional Info, or any datastream fails to
deliver.

These flags cover a partner that takes no account inputs. When the
connection's `partner.inputs` lists an input, its value travels in a fuller
body through `--file`, as
[Deliver to a Partner Endpoint](/guides/deliver-to-a-partner-endpoint) shows. A
`default_value` passes the API's check for a required input but is not copied
into the delivery, so send the value itself.

For a partner without inputs, delivered data lands at the partner's own
destination. See [Activate an Audience](/guides/activate-an-audience).

## What next

The same flow as a file, for anything the flags do not write. Edit the
`audience.json` that `--dry-run` wrote, then:

```bash
intuizi audiences create --file audience.json --wait
```

To deliver only the devices seen on several days, build the audience with
`--frequency`, count a range of days with `intuizi activations preview`, and
pass the same range and the `filter_hash` it prints to
`activations create --freq-min --freq-max --filter-hash`. The frequency
analysis requires additional permissions which need to be approved by your
Account Manager. See [Preview](/cli/reference/activations#preview).

A completed audience can be made recurring, rebuilt on a rolling window every
cycle, with [`intuizi schedules create`](/cli/reference/schedules#create).
Schedules require additional permissions which need to be approved by your
Account Manager. An audience can also become a
[cohort](/cli/reference/cohorts#create) (`intuizi cohorts create --audience-id`)
for reuse as a dataset in a later audience.

{{< cards >}}
  {{< card link="/developers/cli/getting-started/" title="Getting Started" subtitle="Install, log in, first command." >}}
  {{< card link="/developers/cli/reference/" title="Command Reference" subtitle="Every command, its flags, and the endpoint behind each one that calls the API." >}}
{{< /cards >}}