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.

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:

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 says which field each catalog matches. The POI catalogs cascade, so segments narrow categories, categories narrow brands, and brands narrow locations:

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 and Working with Reference Data.

2. Build it

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.

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:

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.

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.

3. Check it

Read the audience back before paying to deliver it:

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

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 {...}:

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.

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:

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

What next

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

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.

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