Skip to content
Create an Audience
.md

Create an Audience

An audience is a definition of who you want to reach. You build it against one or two datasets by selecting filter values that you read from reference data first. This guide covers the single create endpoint, the create-then-poll flow, the fields each dataset type accepts, combining two datasets with an operator, and the optional crossvisitation, cross purchase, and network switching analyses.

There is one create endpoint:

POST /api/v2/analyses/audiences/create

An audience holds one or two datasets. Each dataset travels in the body as an entry in a datasets array with a type - fetch the accepted values from Get Dataset Types. When you supply two datasets you combine them with an operator (AND, OR, or NOTIN); a single dataset takes no operator. The exact, field-level contract is in the API Reference - Audiences; this guide is the narrative.

Prerequisites

  • A bearer token (Authentication).
  • The reference values you want to target. Read them first with Working with Reference Data - every filter below is populated from a reference read, so you send the exact values the builder expects. The per-type sections link each field to its read.

The create flow

  1. Authenticate and get a bearer token.
  2. Build the dataset body - pick each dataset’s type, the window (start_date / end_date for all types except Cohorts and Demographics), and the filters you want from reference data. With two datasets, also pick an operator.
  3. POST the body to /api/v2/analyses/audiences/create. The response returns the new audience id immediately, in status 100 Initiating.
  4. Poll GET /api/v2/analyses/audiences/{id} until the lifecycle status reaches 104 Completed.

The request body

FieldTypeRequiredDescription
namestringYesAudience name (max 255 chars).
operatorstringConditionalHow to combine two datasets: AND, OR, or NOTIN. Required when datasets holds two blocks; rejected (422) when it holds one. Fetch the accepted values from GET /api/v2/analyses/reference/common/operators.
project_idintegerNoA project id owned by your company to file the audience under.
datasetsobject[]YesOne or two dataset blocks (array of size 1 or 2).
analysesobjectNoThe frequency analyses: frequency (POI, with frequency_day_part), apps_frequency (Apps) and web_frequency (WebDomain) run the analysis the activation preview needs; gated, tied to the dataset type, and not available for some dataset combinations - see Frequency analyses.

Each datasets[i] block always carries a type. Except for Cohorts and Demographics, it also carries a start_date and end_date. The remaining fields depend on the type. The accepted type values are the dataset types your company is entitled to, fetchable from GET /api/v2/analyses/reference/common/dataset-types.

Send only the filters you want - on each type they are optional on their own; you just need enough to define a meaningful population.

Combining two datasets

To target the intersection, union, or exclusion of two populations, supply two dataset blocks and an operator:

  • AND - people who match both datasets.
  • OR - people who match either dataset.
  • NOTIN - people who match the first dataset but not the second.

The operator is required whenever you send two datasets, and is rejected if you send only one. Both datasets are validated exactly the same way (each dataset’s ids must exist). A second dataset that is present but missing its type is rejected with 422.

WebDomain windows roll: start_date must fall within the last 45 days of available data at the moment you send the request - substitute a current window for the dates below.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "name": "US auto-intenders on tech sites",
    "datasets": [
      {
        "type": "WebDomain",
        "start_date": "2026-07-01",
        "end_date": "2026-07-28",
        "iab_category_codes": [1, 4],
        "web_domains": ["example.com"],
        "device_types": ["Mobile"],
        "browsers": ["Chrome"],
        "languages": ["en"],
        "location": { "countries": ["USA"] }
      }
    ]
  }'

A two-dataset request

This example combines a WebDomain dataset with an Apps dataset using AND, so the audience is the people who match both:

WebDomain windows roll: start_date must fall within the last 45 days of available data at the moment you send the request - substitute a current window for the dates below.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "name": "Auto-intenders who also run finance apps",
    "operator": "AND",
    "datasets": [
      {
        "type": "WebDomain",
        "start_date": "2026-07-01",
        "end_date": "2026-07-28",
        "iab_category_codes": [1, 4],
        "location": { "countries": ["USA"] }
      },
      {
        "type": "Apps",
        "start_date": "2026-07-01",
        "end_date": "2026-07-28",
        "categories": [12],
        "location": { "countries": ["USA"] }
      }
    ]
  }'
The Idempotency-Key header is optional and you generate it yourself - any unique string (a UUID v4 is typical), one per logical create. Reuse the same key only when retrying the exact same request: the retry replays the original response (Idempotency-Replayed: true) instead of double-creating the audience; the same key with a different body returns 409.

The response

The create response is the freshly queued audience, in status 100 Initiating with results_count 0. The standard { status, code, message, data } envelope wraps it.

{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": [
    {
      "id": 88,
      "name": "US auto-intenders on tech sites",
      "status": { "id": 100, "name": "Initiating" },
      "is_cohort": false,
      "results_count": 0,
      "credits_charged": null,
      "created_at": "2025-01-01 12:00:00"
    }
  ]
}

Dataset fields by type

Every field below is optional unless marked otherwise. The fields backed by a reference catalog link to the read that returns their valid values - fetch those first, then pass the values you collected.

Fields common to all types

These travel directly on each datasets[i] block (except where a type opts out, noted per section).

FieldTypeRequiredDescription
typestringYesThe dataset type. Fetch the types your company is entitled to from Get Dataset Types - a type not enabled for your account is rejected with 422.
start_datestring (Y-m-d)Yes (except Cohorts and Demographics)Window start date.
end_datestring (Y-m-d)Yes (except Cohorts and Demographics)Window end date.
signal_providersstring[]Yes (all types except Cohorts, Demographics and SKUs)BID values identifying the signal source: a list of distinct strings, at most 200. Fetch valid values for the dataset type from GET /api/v2/analyses/reference/common/signal-providers. A provider already used on one of your organization’s audiences of the same dataset type is also accepted, as long as it is still a signal provider. Any other value is rejected with 422 naming it.
languagesstring[]NoLanguage codes. Fetch valid values from GET /api/v2/analyses/reference/common/languages.
locationobjectcountries required (all types except Cohorts, Transactions and SKUs)A { countries[], states[], cities[], dmas[], zipcodes[] } block. countries come from GET /api/v2/analyses/reference/common/countries; states cascade from countries via GET /api/v2/analyses/reference/common/states; cities cascade from states via GET /api/v2/analyses/reference/common/cities; dmas (POI, Origin and Connectivity only) come from GET /api/v2/analyses/reference/common/dmas.

Cohorts takes neither dates nor location. Apps, Demographics, Deidentified and ProfileAttributes read location.countries only; WebDomain and CTV read the full location block. POI requires location.countries and also reads states, cities, dmas and zipcodes. Origin requires location.countries and reads the same states, cities, dmas and zipcodes; its window is widened to whole Monday-to-Sunday weeks. Connectivity reads the same location block and widens its window the same way. AffinityTransactions is United States only: location.countries is optional there and it reads states, cities and zipcodes; its recency end_date cannot run past the most recent fully-settled purchase week (the latest Sunday at least 11 days before today, UTC, which advances each Thursday). The crosspurchase analysis reads the same purchase data and shares that same end-date cap. WebDomain reads archive-limited visitation data: its start_date must fall within the last 45 days of available data, and an earlier date is rejected with 422. Demographics takes no dates and no signal providers. SKUs takes no signal providers either: its location.countries is optional, and it reads location.states. ProfileAttributes covers whole quarters inside a delivered window.

Web Domain

Targets people by the domains they visit, plus their device and location. Set type to WebDomain.

start_date must fall within the last 45 days of available data: web data lands with a ~48-hour delay, so the window ends two days ago (UTC). Older visitation data is archived and unreadable - an earlier start_date is rejected with 422. The window rolls forward one day at UTC midnight.

FieldTypeRequiredDescription
iab_category_codesinteger[]One of iab_category_codes / web_domainsIAB category ids. Fetch valid values from GET /api/v2/analyses/reference/web/iab-categories (and subcategories from GET /api/v2/analyses/reference/web/iab-subcategories).
web_domainsstring[]One of iab_category_codes / web_domainsWeb domains to target. Domains must exist in the catalog - fetch valid values from GET /api/v2/analyses/reference/web/domains; a domain outside the catalog is rejected with 422.
web_ref_domainsstring[]NoReferrer domains to target. Fetch valid values from GET /api/v2/analyses/reference/web/ref-domains.
device_typesstring[]NoWeb device type names. Fetch valid values from GET /api/v2/analyses/reference/web/device-types.
device_makesstring[]NoWeb device make names. Fetch valid values from GET /api/v2/analyses/reference/web/device-makes.
device_osesstring[]NoWeb device OS names. Fetch valid values from GET /api/v2/analyses/reference/web/device-oses.
browsersstring[]NoWeb browser names. Fetch valid values from GET /api/v2/analyses/reference/web/browsers.
max_devices_per_ipintegerNoMatch strictness: how many devices may share one household/IP. 1 (very strict) to 5 (more reach). Defaults to 3 (recommended).

Connected TV

Targets people by the streaming content and devices they use. Set type to CTV. CTV filters are matched by name, not numeric id.

FieldTypeRequiredDescription
ctv_vendor_namesstring[]NoCTV vendor names. Fetch valid values from GET /api/v2/analyses/reference/ctv/vendors.
ctv_content_type_namesstring[]NoNo longer supported: no CTV data provider supplies content types, so a list with values is refused with 422. Leave it out or send it empty.
ctv_content_genre_namesstring[]NoCTV content genre names. Fetch valid values from GET /api/v2/analyses/reference/ctv/content-genres.
ctv_channel_namesstring[]NoCTV channel names. Fetch valid values from GET /api/v2/analyses/reference/ctv/channel-names.
iab_codesarrayNoIAB codes. Fetch valid values from GET /api/v2/analyses/reference/web/iab-categories.
ctv_device_typesstring[]NoCTV device type names. Fetch valid values from GET /api/v2/analyses/reference/ctv/device-types.
ctv_device_makesstring[]NoCTV device make names. Fetch valid values from GET /api/v2/analyses/reference/ctv/device-makes.
ctv_device_osesstring[]NoCTV device OS names. Fetch valid values from GET /api/v2/analyses/reference/ctv/device-oses.
ctv_connection_typesstring[]NoCTV connection type names. Fetch valid values from GET /api/v2/analyses/reference/ctv/connection-types.
ctv_ispsstring[]NoCTV ISP names. Fetch valid values from GET /api/v2/analyses/reference/ctv/isps.
ctv_seriesstring[]NoCTV series names. Fetch valid values from GET /api/v2/analyses/reference/ctv/series.

Cohorts

Reuses one of your own completed cohorts as an audience. Set type to Cohorts. Cohorts are company-scoped: you can only target a completed cohort that belongs to your company. This type takes no dates and no location.

FieldTypeRequiredDescription
cohort_idintegerYesA completed cohort id owned by your company. Fetch valid ids from GET /api/v2/analyses/reference/cohorts/get-cohorts.

Apps

Targets people by the mobile apps they have and the categories those apps belong to. Set type to Apps. Apps reads location.countries only.

FieldTypeRequiredDescription
app_idsinteger[]At least one of categories / taxonomies / bundle_ids / app_idsApp ids to target. Fetch valid ids from GET /api/v2/analyses/reference/apps/bundle-ids.
bundle_idsstring[]At least one of categories / taxonomies / bundle_ids / app_idsApp bundle ids to target. Fetch valid values from GET /api/v2/analyses/reference/apps/bundle-ids.
categoriesarrayAt least one of categories / taxonomies / bundle_ids / app_idsApp category ids. Fetch valid values from GET /api/v2/analyses/reference/apps/categories.
taxonomiesarrayAt least one of categories / taxonomies / bundle_ids / app_idsApp taxonomy ids. Fetch valid values from GET /api/v2/analyses/reference/apps/taxonomies.
device_osstring[]NoApp device OS values. Fetch valid values from GET /api/v2/analyses/reference/apps/os.
refineobjectNoPost-build refinement: keep only the most active devices. Permission-gated, single-dataset audiences only - see Refine.

App tags narrow the targeted set; fetch valid values from GET /api/v2/analyses/reference/apps/tags.

Apps location supports countries only: sending location.states, location.cities, location.dmas, or location.zipcodes on an Apps dataset is rejected with 422.

POI

Targets people by the points of interest (POIs) they physically visited. Set type to POI. The POI catalogs form a cascade - pick segments, use them to read categories, categories to read brands, and brands to read individual locations:

segments -> categories (?segments[]) -> brands (?categories[]) -> locations (?brands[])

A POI dataset can instead be built from the attributes scheduled at locations: set poi_selection_mode to attributes and send the pick in poi_attributes, see POI attributes below. The attribute catalogs cascade too:

attributes -> attribute-values (?attribute_id)

Unlike the other dataset types, POI requires location.countries (at least one country). The dataset also accepts an optional time-of-day window (time_limits) and a distance radius (distance_limits).

FieldTypeRequiredDescription
categoriesinteger[]At least one of categories / analysisdata / locations in categorization mode, absent or empty in attributes modePOI category ids. Fetch valid values from GET /api/v2/analyses/reference/poi/categories (cascades from segments read via GET /api/v2/analyses/reference/poi/segments).
analysisdatainteger[]At least one of categories / analysisdata / locations in categorization mode, absent or empty in attributes modePOI brand ids. Fetch valid values from GET /api/v2/analyses/reference/poi/brands (cascades from categories).
locationsarrayAt least one of categories / analysisdata / locations in categorization mode, absent or empty in attributes modePOI location identifiers. Fetch candidates from GET /api/v2/analyses/reference/poi/locations (cascades from brands). How the values are interpreted is set by location_identifier_type.
location_identifier_typestringNoHow locations are interpreted: none, location_id, external_id, store_id, placekey, h3_index, or h3_index_integer.
poi_selection_modestringNoHow the dataset picks its places. categorization (the default) reads categories, analysisdata and locations. attributes reads poi_attributes, see POI attributes below.
poi_attributesarrayYes in attributes mode, absent or empty otherwiseThe attribute values to build from, as [{ attribute_id, value_ids[] }] with at least one value id per attribute. Fetch attribute ids from GET /api/v2/analyses/reference/poi/attributes and value ids from GET /api/v2/analyses/reference/poi/attribute-values (cascades from attributes).
signal_providersstring[]YesBID values identifying the signal source. Fetch valid values from GET /api/v2/analyses/reference/common/signal-providers. A provider already used on one of your organization’s audiences of the same dataset type is also accepted, as long as it is still a signal provider.
location.countriesstring[]YesCountry codes (at least one). Fetch from GET /api/v2/analyses/reference/common/countries.
location.statesstring[]NoState codes. Cascade from countries via GET /api/v2/analyses/reference/common/states.
location.citiesstring[]NoCity names. Cascade from states via GET /api/v2/analyses/reference/common/cities.
location.dmasstring[]NoDMA market labels. Fetch from GET /api/v2/analyses/reference/common/dmas.
location.zipcodesstring[]NoZIP codes. Cascade from cities via GET /api/v2/analyses/reference/common/zipcodes (paginated).
time_limitsobjectNo{ process: boolean, start: 0-23, end: 0-23 } - restrict to an hour-of-day window when process is true.
day_limitsobjectNo{ process: boolean, days: integer[] } - restrict to days of the week when process is true; ISO numbering (1 = Monday .. 7 = Sunday).
distance_limitsobjectNo{ process: boolean, distance: number, unit: "miles" | "kilometers" } - restrict to visits within a radius when process is true.
refineobjectNoPost-build refinement: keep only the most active devices. Permission-gated, single-dataset audiences only - see Refine.
filtersstring[]NoQuality filters: any of anomalous_devices, anomalous_pois, strict_gps. Left out (or null), the default set anomalous_devices + strict_gps applies; [] turns every filter off - see POI filters below.

POI attributes

In attributes mode a POI dataset is built from attributes scheduled at locations instead of from categories, brands and locations. Read the attribute ids, then the value ids of each attribute, and send them in poi_attributes. The dataset is built from the locations where any of the selected values is scheduled. Only visits inside each location’s scheduled event windows count.

Leave categories, analysisdata and locations out in this mode: they come from the locations the values are scheduled at. The selected values must be scheduled at one location or more, with at least one scheduled event between start_date and end_date. The dates can cover at most five years (1,827 days), and poi_attributes takes up to 50 attributes with up to 500 value ids each.

{
  "type": "POI",
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "signal_providers": ["BID001"],
  "location": { "countries": ["USA"] },
  "poi_selection_mode": "attributes",
  "poi_attributes": [
    { "attribute_id": 3, "value_ids": [9] }
  ]
}

POI filters

A POI dataset takes the Audience Manager’s POI quality filters as filters. When you leave filters out (or send null), the default set applies: anomalous_devices and strict_gps. The Audience Manager uses the same default, so the same recipe gives the same size on every surface.

  • Default: leave filters out. The audience gets anomalous_devices and strict_gps, and its normalized_payload shows them.
  • No filters: send "filters": [] (the CLI uses --no-filters).
  • Your own set: send the list. Exactly that list applies, with no default added to it. Send ["anomalous_devices"] to keep the bad-device filter and turn strict_gps off.
ValueWhat it removes
anomalous_devicesDevices on Intuizi’s list of known bad devices.
anomalous_poisEvery visit to locations flagged as anomalous.
strict_gpsEvery visit at a spot where more than 500 devices from one signal provider were seen in the same calendar month (for the current month, the newest month whose list is published). A spot is the coordinates rounded to 4 decimals (about 11 m). These are data errors, such as city-center points and grid points that a provider reports for many devices at once.

anomalous_pois stays available. It is off by default.

strict_gps is on by default and makes new audiences smaller than they were without filters. For example, Starbucks stores in California for October 2026 hold 102.8M devices with no filters and 3.5M with the default set. Turn strict_gps off for airports and stadiums, where real crowds can stand on one spot and the filter removes them too. Send ["anomalous_devices"] for those.

The filters apply to every POI dataset in the audience, not to its other dataset types. When both datasets are POI, they must resolve to the same filters. Leaving filters out on one and sending the default set on the other is accepted. Two different sets are rejected with 422. Unknown values are rejected with 422, and so is filters on any other dataset type.

Next to an AffinityTransactions dataset no default applies, because the filters do not apply there. A non-empty filters list is rejected with 422 there, and filters: [] is accepted.

Stored audiences and schedulers keep the filters they were created with. Cloning one, or running a scheduler, does not add the default. Only a new request that leaves filters out gets it.

{
  "type": "POI",
  "start_date": "2026-06-01",
  "end_date": "2026-08-31",
  "signal_providers": ["BID001"],
  "categories": [101],
  "location": { "countries": ["USA"] },
  "filters": ["anomalous_devices", "strict_gps"]
}

Transactions

Targets people by what they actually bought. Set type to AffinityTransactions. The purchase catalogs form a cascade - pick categories, use them to read sub-categories, and both to read brands:

categories -> subcategories (?categories[]) -> brands (?categories[], ?subcategories[])

At least one categories or brands value is required - without one the dataset has no purchase filter. Sub-categories are the merchant category description strings the sub-categories read returns (not ids); picked without any brands, they are resolved to the brands they cover.

Affinity purchase data is United States only, so location.countries is optional here and always stored as ["USA"]. Sending any other country code is rejected with 422, as is location.dmas - this type reads location.states, location.cities and location.zipcodes only.

FieldTypeRequiredDescription
categoriesinteger[]At least one of categories / brandsAffinity purchase category ids. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/categories.
brandsstring[]At least one of categories / brandsAffinity brand id strings. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/brands (cascades from categories and sub-categories).
subcategoriesstring[]NoSub-category strings cascading from categories. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/subcategories.
incomesstring[]NoIncome bands. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/incomes.
agesstring[]NoAge bands. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/ages.
gendersstring[]NoGender values. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/genders.
ethnicitiesstring[]NoEthnicity values. Fetch valid values from GET /api/v2/analyses/reference/affinity-transactions/ethnicities.
channelsstring[]NoPurchase channel: B&M (in-store) and/or ONLINE.
spend_minnumberNoMinimum total spend (USD) across the date window.
spend_maxnumberNoMaximum total spend (USD) across the date window.
txn_minnumberNoMinimum number of transactions across the date window.
txn_maxnumberNoMaximum number of transactions across the date window.
analysis_spend_frequencybooleanNoAlso compute the spend distribution for the built audience. Defaults to false.
analysis_transactions_frequencybooleanNoAlso compute the transaction-count distribution for the built audience. Defaults to false.
max_devices_per_ipintegerNoMatch strictness: how many devices each shopper may expand to. 1 (very strict) to 5 (more reach). Defaults to 3 (recommended).
{
  "type": "AffinityTransactions",
  "start_date": "2025-01-01",
  "end_date": "2025-03-31",
  "signal_providers": ["BID001"],
  "categories": [1],
  "subcategories": ["Eating Places, Restaurants"],
  "brands": ["501"],
  "incomes": ["100k-150k"],
  "channels": ["B&M"],
  "spend_min": 50,
  "txn_min": 2,
  "max_devices_per_ip": 3,
  "location": { "states": ["CA"] }
}

Demographics

Targets people by their household demographic attributes. Set type to Demographics. The four dictionaries are flat - there is no cascade - and at least one of them must carry a selection, otherwise the dataset has no filter.

A Demographics dataset reads one monthly vintage of the demographics data, the latest complete one when the audience or estimate runs. The audience’s dataset entry and the estimate name that month in vintage (YYYY-MM), and its numbers read as “latest monthly vintage, as of YYYY-MM”. An audience or estimate made before 2026-10-24 carries no vintage: it read every monthly vintage at once, so its numbers are about 3 to 4 times larger.

This type carries no date window and no signal providers: sending start_date, end_date or signal_providers is rejected with 422. Its location supports countries only (at least one is required), so location.states, location.cities, location.zipcodes and location.dmas are rejected too.

FieldTypeRequiredDescription
gendersstring[]At least one of genders / ages / marital_statuses / incomesGender values. Fetch valid values from GET /api/v2/analyses/reference/demographics/genders.
agesstring[]At least one of genders / ages / marital_statuses / incomesAge ranges. Fetch valid values from GET /api/v2/analyses/reference/demographics/ages.
marital_statusesstring[]At least one of genders / ages / marital_statuses / incomesMarital status values. Fetch valid values from GET /api/v2/analyses/reference/demographics/marital-statuses.
incomesstring[]At least one of genders / ages / marital_statuses / incomesIncome ranges. Fetch valid values from GET /api/v2/analyses/reference/demographics/incomes.
location.countriesstring[]YesCountry codes (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/countries.
{
  "type": "Demographics",
  "genders": ["F"],
  "ages": ["25-34", "35-44"],
  "incomes": ["100k-150k"],
  "location": { "countries": ["USA"] }
}

Deidentified

Delivers the deidentified signals themselves for a country and date window, rather than a targeted device list. Set type to Deidentified. Instead of filters it takes fields: which signal fields the delivery carries.

fields is an object keyed by group (geoLocation, advertising, userDetails, ipDetails, privacy, general). Every group is optional - send only the groups you want, or omit fields entirely for the default shape. Fetch the fields and the group each belongs to from GET /api/v2/analyses/reference/deidentified/fields; an unknown field, or a field sent under a group it does not belong to, is rejected with 422.

This type is delivered on its own: an audience whose dataset is Deidentified takes exactly one dataset block, so pairing it with a second one (and therefore an operator) is rejected with 422.

Its location supports countries only, so location.states, location.cities, location.zipcodes and location.dmas are rejected. When location.countries includes USA, the date window may cover at most two weeks per delivery.

The window can always start on the first day of the previous month or later. A start_date before the earliest day the Audience Manager offers in any time zone is rejected with 422, and the message names that day. Your Account Manager can enable a longer look-back for your account.

FieldTypeRequiredDescription
fieldsobjectNoWhich signal fields the delivery carries, keyed by group. Fetch the fields and their groups from GET /api/v2/analyses/reference/deidentified/fields.
signal_providersstring[]YesBID values identifying the signal source (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/signal-providers. A provider already used on one of your organization’s audiences of the same dataset type is also accepted, as long as it is still a signal provider.
start_datestring (Y-m-d)YesWindow start, inside the look-back described above.
end_datestring (Y-m-d)YesWindow end. At most two weeks after start_date when location.countries includes USA.
location.countriesstring[]YesCountry codes (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/countries.

The dates in this block only show the format: send a window inside the look-back described above.

{
  "type": "Deidentified",
  "start_date": "2026-10-01",
  "end_date": "2026-10-12",
  "signal_providers": ["BID001"],
  "fields": {
    "geoLocation": ["latitude", "longitude"],
    "ipDetails": ["ipisp"],
    "general": ["d_utc"]
  },
  "location": { "countries": ["USA"] }
}

Profile Attributes

Targets people by the profile attributes they carry. Set type to ProfileAttributes. An attribute is a category, a key under that category, and the values of that key to match; the values of one attribute are alternatives. Send the attributes in one of two shapes:

  • profile_attributes: a list of attributes combined with AND - a device must match every one.
  • profile_attribute_groups: 1 to 5 groups, combined with AND. A group with match: "all" requires every attribute in it, a group with match: "any" at least one.

A block takes one of the two, never both (422). A single group with match: "all" builds exactly the same audience as profile_attributes.

The attribute catalogs form a three-level cascade - pick a category, use it to read the keys under it, and both to read that key’s values:

categories -> keys (?category_ids[]) -> values (?category_ids[], ?key)

Each attribute is checked at all three levels: an unknown category, a key that does not belong to the attribute’s category, or a value that does not belong to its category and key is rejected with 422 naming the exact field: datasets.<i>.profile_attributes.<n>.<field> or datasets.<i>.profile_attribute_groups.<g>.attributes.<n>.<field>. Indexes count from 0.

A profile_attributes row takes no group or match: sending either is rejected with 422, so use profile_attribute_groups to group attributes. An attribute inside a group takes only category_id, key, and value_ids.

Its location supports countries only, so location.states, location.cities, location.zipcodes and location.dmas are rejected.

Profile attribute data is delivered quarterly. start_date and end_date must fall inside the delivered window published by GET /api/v2/analyses/reference/profile-attributes/recency-limits; a date outside it is rejected with 422. The stored window is expanded out to whole quarters - start_date to the first day of its quarter and end_date to the last day of its quarter.

FieldTypeRequiredDescription
profile_attributesobject[]One of the twoAttributes (at least one), combined with AND.
profile_attributes[].category_idintegerYesAn attribute category id. Fetch valid values from GET /api/v2/analyses/reference/profile-attributes/categories.
profile_attributes[].keystringYesAn attribute key under that category. Fetch valid values from GET /api/v2/analyses/reference/profile-attributes/keys (cascades from categories).
profile_attributes[].value_idsinteger[]YesValue ids of that key (at least one). Fetch valid values from GET /api/v2/analyses/reference/profile-attributes/values (cascades from categories and the key).
profile_attribute_groupsobject[]One of the two1 to 5 attribute groups, combined with AND.
profile_attribute_groups[].matchstringYesall (every attribute in the group must match) or any (at least one must).
profile_attribute_groups[].attributesobject[]YesThe group’s attributes (at least one), each with category_id, key and value_ids exactly like a profile_attributes row.
signal_providersstring[]YesBID values identifying the signal source (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/signal-providers. A provider already used on one of your organization’s audiences of the same dataset type is also accepted, as long as it is still a signal provider.
start_datestring (Y-m-d)YesWindow start, inside the delivered window.
end_datestring (Y-m-d)YesWindow end, inside the delivered window.
location.countriesstring[]NoAccepted but never applied - this dataset has no geography. Safe to omit.
{
  "type": "ProfileAttributes",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "signal_providers": ["BID001"],
  "profile_attributes": [
    { "category_id": 1, "key": "auto_intent", "value_ids": [10, 12] },
    { "category_id": 2, "key": "credit_band", "value_ids": [30] }
  ]
}

The same dataset with groups - both attributes of the first group required, and at least one of the second group’s:

{
  "type": "ProfileAttributes",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "signal_providers": ["BID001"],
  "profile_attribute_groups": [
    { "match": "all", "attributes": [
      { "category_id": 1, "key": "auto_intent", "value_ids": [10, 12] },
      { "category_id": 2, "key": "credit_band", "value_ids": [30] }
    ] },
    { "match": "any", "attributes": [
      { "category_id": 3, "key": "hunting", "value_ids": [41] },
      { "category_id": 3, "key": "fishing", "value_ids": [42] }
    ] }
  ]
}

Origin

Targets people by their home location - where a device originates - rather than by the places it visited. Set type to Origin. Each device’s home is resolved once per week and placed by point-in-polygon against the ZIP code and DMA boundaries, so every filter narrows that resolved home location.

Its only filters are geographic: location.countries is required, and states, cities, dmas and zipcodes are optional. signal_providers is required as for the other dated types.

Its data is weekly - a device’s home is resolved once per week, and there is no day in the data - so a sub-week window cannot exist. Any dates are accepted, and the window is widened to the whole Monday-to-Sunday weeks it touches: Tuesday to Friday builds, and is stored as, that full week.

Origin data exists for a limited set of countries. Fetch the covered set from GET /api/v2/analyses/reference/common/countries with ?datasetType=Origin; a country outside it is rejected with 422.

FieldTypeRequiredDescription
signal_providersstring[]YesBID values identifying the signal source (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/signal-providers with ?dataType=Origin.
start_datestring (Y-m-d)YesWindow start. Widened back to the Monday of its week.
end_datestring (Y-m-d)YesWindow end, on or after start_date. Widened forward to the Sunday of its week.
location.countriesstring[]YesCountry codes (at least one) with Origin coverage. Fetch valid values from GET /api/v2/analyses/reference/common/countries with ?datasetType=Origin.
location.statesstring[]NoState codes. Fetch valid values from GET /api/v2/analyses/reference/common/states.
location.citiesstring[]NoCity names. Fetch valid values from GET /api/v2/analyses/reference/common/cities.
location.dmasstring[]NoDMA labels exactly as returned by GET /api/v2/analyses/reference/common/dmas - the label string, never a numeric code.
location.zipcodesstring[]NoZIP codes. Fetch valid values from GET /api/v2/analyses/reference/common/zipcodes.
{
  "type": "Origin",
  "start_date": "2026-08-31",
  "end_date": "2026-09-13",
  "signal_providers": ["BID001"],
  "location": {
    "countries": ["USA"],
    "states": ["CA"],
    "dmas": ["803 - Los Angeles, CA"]
  }
}

Connectivity

Targets devices by the network they used: the home internet network or the mobile carrier a device was on for most days of a week. Set type to Connectivity. The dataset is available on request.

Its data is weekly. Any dates are accepted, and the window is widened to whole Monday-to-Sunday weeks. The stored window then runs from the Monday of the first built week to the Sunday of the last built week inside that range, so a start in a week that is not built moves forward to the next built week. Dates that touch no built week are refused with a 422 that names the weeks that are built.

Each signal source needs data in at least one week of the window. With a home area (states, cities, dmas or zipcodes), each source must also feed Origin, and the area narrows the devices to those whose Origin home of the same week is in it.

FieldTypeRequiredDescription
signal_providersstring[]YesBID values identifying the signal source (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/signal-providers with ?dataType=Connectivity.
start_datestring (Y-m-d)YesWindow start. Widened back to its Monday, then moved to the oldest built week if earlier.
end_datestring (Y-m-d)YesWindow end, on or after start_date. Widened forward to its Sunday, then moved to the newest built week if later.
connectivity_network_kindstringYeshome or mobile.
connectivity_networksstring[]NoNames from GET /api/v2/analyses/reference/connectivity/networks for the kind. The list holds curated brands only. Leave it empty for any home network (or any mobile carrier), including networks that are not in the list.
connectivity_technologiesstring[]NoHome only: Fiber, Cable, DSL, Cable or DSL, Satellite or Fixed wireless. Empty means any. Technologies are home only and are empty for a mobile carrier.
connectivity_min_daysintegerNoMinimum days of a week a device used the network, 1 to 7. Default 3.
location.countriesstring[]YesCountry codes (at least one). Fetch valid values from GET /api/v2/analyses/reference/common/countries with ?datasetType=Connectivity.
location.states / cities / dmas / zipcodesstring[]NoA home area, as for Origin.

NOT IN is not available with a Connectivity block yet.

{
  "type": "Connectivity",
  "start_date": "2026-09-23",
  "end_date": "2026-10-21",
  "signal_providers": ["BID001"],
  "location": { "countries": ["USA"] },
  "connectivity_network_kind": "home",
  "connectivity_networks": ["Starlink"],
  "connectivity_technologies": ["Satellite"]
}

SKUs

Targets the devices seen on the home networks of the purchases of a product brand, or of the purchases from a merchant, online. Set type to SKUs. The dataset is available on request.

The data is online purchases at product level from a panel of affiliate-tracked orders, and it is strongest at large United States retailers. The audience holds the devices seen on the home network each purchase click came from, so an order with no tracked click adds no device. See SKUs.

Name merchants, brands or categories, or several of them. The values of one list are alternatives, and the lists narrow each other on the same order line (a brand with a category is that brand bought in that category). A SKUs block takes no signal_providers, and its location reads countries and states only. To keep only the heavier buyers, add the spend filters: spend_top_percent keeps the top share of home networks by spend, and spend_min, orders_min and item_price_min set bounds (see Spend filters).

A SKUs dataset combines with one other dataset of the types Combining a SKUs dataset lists, and an audience with a SKUs dataset takes no analysis and no refine.

FieldTypeRequiredDescription
start_datestring (Y-m-d)YesThe first purchase day of the window. See Coverage and freshness for the first day with data, the days with no or few purchases, and the newest days.
end_datestring (Y-m-d)YesThe last purchase day of the window, on or after start_date.
merchantsstring[]One of merchants / brands / categoriesMerchant keys. Fetch valid values from GET /api/v2/analyses/reference/skus/merchants.
brandsstring[]One of merchants / brands / categoriesProduct brand keys. Fetch valid values from GET /api/v2/analyses/reference/skus/brands, with search (and categories to list the brands sold under them).
categoriesinteger[]One of merchants / brands / categoriesCategory ids; a category selects itself and every category under it. Fetch valid values from GET /api/v2/analyses/reference/skus/categories (parent_id to walk the tree, or search).
device_types, device_oses, device_makes, device_modelsstring[]NoThe device of the purchase click. Fetch valid values from GET /api/v2/analyses/reference/skus/device-values (field type, os, make, model).
max_devices_per_ipintegerNoMatch Strictness, 1 (very strict) to 5 (more reach). Default 3.
item_price_min, item_price_max, spend_min, spend_max, orders_min, orders_max, spend_top_percentnumber / integerNoSpend filters: the price of an item, what a home network spent, its orders, and the top share of spenders (50, 25, 10, 5 or 1).
location.countriesstring[]NoCountry codes. Fetch valid values from GET /api/v2/analyses/reference/common/countries. Left out, the purchases of every country are read.
location.statesstring[]NoState codes. Fetch valid values from GET /api/v2/analyses/reference/common/states.
{
  "type": "SKUs",
  "start_date": "2026-10-01",
  "end_date": "2026-10-31",
  "brands": ["dove", "dove men+care"],
  "location": { "countries": ["USA"] },
  "spend_top_percent": 10,
  "orders_min": 2
}

Refine the audience

POI and Apps datasets accept an optional refine object that refines the audience after it is built: devices are ranked by a behavioral metric and only a subset is kept - the top X% (percentile), everyone at or above a minimum event count (threshold), or the top N devices (rank). The refined audience keeps its full data shape; results_count and every downstream activation reflect the refined device set.

Refine applies to single-dataset audiences only - a refine block on either dataset of a two-dataset audience, or on any other dataset type, is rejected with 422.

Refine is a gated feature. It requires additional permissions that your Account Manager can enable for your account. If a refine block is present and the feature is not enabled, the request is rejected with 403 - it is never silently ignored. Omitting the block entirely requires nothing.
FieldTypeRequiredDescription
typestringYesHow the subset is selected: percentile (keep the top X% by the metric), threshold (keep devices with at least value events), or rank (keep the top value devices).
metricstringYesThe behavioral metric to rank devices by. POI: visit_count or visit_days. Apps: app_usage_count or app_usage_days.
valuenumberYesMeaning depends on type: the percentage to keep for percentile (greater than 0 and less than 100), the minimum event count for threshold, or the number of devices for rank (whole number, at least 1).
fraud_cutoff_percentileintegerNoDrop outlier devices above this activity percentile (1-100, e.g. 99) before the cut, so bot-like devices do not crowd out the subset you keep.
max_valueintegerNoUpper bound on the metric, threshold type only - keeps devices between value and max_value events. Rejected with 422 on the other types.

For example, to keep only the devices in the top 10% by visit frequency, dropping the top 1% as likely bots:

{
  "name": "Frequent coffee shop visitors",
  "datasets": [{
    "type": "POI",
    "start_date": "2025-01-01",
    "end_date": "2025-03-31",
    "signal_providers": ["BID001"],
    "categories": [101],
    "location": { "countries": ["USA"] },
    "refine": {
      "type": "percentile",
      "metric": "visit_count",
      "value": 10,
      "fraud_cutoff_percentile": 99
    }
  }]
}

Crossvisitation

Crossvisitation narrows the audience to people who physically visited points of interest (POIs) you select - by category, by brand, or by specific locations - within a date window and optional time-of-day and distance limits. It travels in the body as an optional top-level crossvisitation object alongside datasets.

Crossvisitation is a gated feature. It requires additional permissions that your Account Manager can enable for your account. If a crossvisitation block is present and the feature is not enabled, the request is rejected with 403 - it is never silently ignored. Omitting the block entirely requires nothing.

Like the frequency analyses, crossvisitation is not available for some dataset combinations: the Audience Manager disables it there, and the API rejects the block with 422 (see Frequency analyses).

Where the POI ids come from

Pick the POI values from the read-only Dataset Types - POI catalogs - the same source as every other audience-builder field. (Creating and managing the underlying POI data itself is the separate My POI Data surface; see Submit POI Data.)

Crossvisitation fields

FieldTypeRequiredDescription
start_datestring (Y-m-d)YesStart of the visitation window.
end_datestring (Y-m-d)YesEnd of the visitation window.
poi_levelbooleanNoResolve at the individual-POI level rather than the parent brand/category.
filtersstring[]NoQuality filters. Any of anomalous_devices, gps_only, anomalous_pois. The POI default set does not apply here: none unless you send them.
categoriesinteger[]Yes (exactly one)A single POI category id (see above). The block requires exactly one category.
brandsinteger[]NoPOI brand ids (see above).
locationsarrayNoPOI location identifiers. Their kind is set by location_identifier_type.
location_identifier_typestringNoHow the locations values are interpreted: none, location_id, external_id, store_id, placekey, h3_index, or h3_index_integer.
locationobjectcountries requiredGeographic scope: { countries[], states[], cities[], dmas[], zipcodes[] } - countries needs at least one entry, the rest are optional. countries come from GET /api/v2/analyses/reference/common/countries.
time_limitsobjectNo{ process: boolean, start: 0-23, end: 0-23 } - restrict to an hour-of-day window when process is true.
day_limitsobjectNo{ process: boolean, days: integer[] } - restrict to days of the week when process is true; ISO numbering (1 = Monday .. 7 = Sunday).
distance_limitsobjectNo{ process: boolean, distance: number, unit: "miles" | "kilometers" } - restrict to visits within a radius when process is true.

A crossvisitation example

Crossvisitation is available only for the POI dataset. This combines a POI dataset with a crossvisitation block that narrows it to visitors of specific POI brands within a date window and a distance limit:

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "name": "Coffee-shop cross visitors",
    "datasets": [
      {
        "type": "POI",
        "start_date": "2025-01-01",
        "end_date": "2025-03-31",
        "signal_providers": ["BID001"],
        "categories": [10],
        "location": { "countries": ["USA"] }
      }
    ],
    "crossvisitation": {
      "start_date": "2025-01-01",
      "end_date": "2025-03-31",
      "poi_level": true,
      "filters": ["anomalous_devices"],
      "categories": [10],
      "brands": [55, 56],
      "location": { "countries": ["USA"] },
      "distance_limits": { "process": true, "distance": 5, "unit": "miles" }
    }
  }'
Crossvisitation shapes how the audience is built, but it is not echoed back on the read endpoints. GET /api/v2/analyses/audiences/{id} returns the datasets and operator, not the crossvisitation block. Keep your own copy of what you sent.

Cross Purchase

Cross purchase runs the built audience against the affinity purchase data: the audience’s devices are matched into purchase transactions within your date window, scoped to the target categories, sub-categories and brands you select. It travels in the body as an optional top-level crosspurchase object alongside datasets. Because it runs on the finished audience, it is available with any dataset combination - one or two datasets, any type. The one exception is a body that also carries a networkswitching block (see Network Switching): the two cannot run together, and the request is rejected with 422. The analysis results are surfaced in the Audience Manager alongside the audience.

Cross purchase is a gated feature. It requires additional permissions that your Account Manager can enable for your account. If a crosspurchase block is present and the feature is not enabled, the request is rejected with 403 - it is never silently ignored. Omitting the block entirely requires nothing.

Pick the target values from the read-only Transactions catalogs - they cascade (categories -> subcategories -> brands), and any mix works: at least one target across the three arrays is required.

FieldTypeRequiredDescription
start_datestring (Y-m-d)YesStart of the purchase window.
end_datestring (Y-m-d)YesEnd of the purchase window. The range may cover at most 2 calendar months.
target_categoriesinteger[]At least one of target_categories / target_subcategories / target_brandsAffinity category ids. From GET /api/v2/analyses/reference/affinity-transactions/categories.
target_subcategoriesstring[]At least one of target_categories / target_subcategories / target_brandsAffinity sub-category strings. From GET /api/v2/analyses/reference/affinity-transactions/subcategories.
target_brandsstring[]At least one of target_categories / target_subcategories / target_brandsAffinity brand id strings. From GET /api/v2/analyses/reference/affinity-transactions/brands.

For example, to report how a POI audience purchases across dining brands:

{
  "name": "Coffee visitors vs dining purchases",
  "datasets": [{
    "type": "POI",
    "start_date": "2025-01-01",
    "end_date": "2025-03-31",
    "signal_providers": ["BID001"],
    "categories": [101],
    "location": { "countries": ["USA"] }
  }],
  "crosspurchase": {
    "start_date": "2025-01-01",
    "end_date": "2025-02-28",
    "target_categories": [1],
    "target_brands": ["501"]
  }
}

Network Switching

Network switching compares the built audience across two months. The audience is one Connectivity dataset. For each device the analysis finds the home internet network (or, on request, the mobile carrier) in one week of each month. It then counts the devices that kept their network, changed it, and switched, in total, per network, and per pair of networks. It travels in the body as an optional top-level networkswitching object alongside datasets. Every count is a count of devices, and any other audience is rejected with 422.

Network switching is a gated feature. It requires additional permissions which need to be approved by your Account Manager. If a networkswitching block is present and the feature is not enabled, the request is rejected with 403 - it is never silently ignored. Omitting the block entirely requires nothing.

Network switching cannot run together with cross purchase. A body that carries both a crosspurchase and a networkswitching block is rejected with 422, naming crosspurchase.

Each month is represented by its last full Monday-to-Sunday week: 2026-09 is September 21 to 27, 2026, and 2026-10 is October 19 to 25, 2026. Both weeks must be built for the dataset’s signal providers: a week counts when at least one of them has data in it. A month whose last full week is not built is rejected with 422, which names the window and the weeks that are built. Both network_type values work, and the dataset keeps its own dates, which do not have to cover either week.

FieldTypeRequiredDescription
network_typestringNohome (the default) compares the home internet network of each device. mobile compares its mobile carrier.
from_monthstring (YYYY-MM)YesThe month of the first week. It must be before to_month and at most 12 months before it, and its last full week must be built.
to_monthstring (YYYY-MM)YesThe month of the second week. Its last full week must be built.
min_home_daysintegerNoThe fewest days of the 7 of a week on which a device must be seen on a network for it to be the device’s home network in that week. 2 to 5, default 3.

For example, to count the devices in the United States that switched to or from Starlink between September and October 2026:

{
  "name": "Starlink switching - September to October 2026",
  "datasets": [{
    "type": "Connectivity",
    "start_date": "2026-10-19",
    "end_date": "2026-10-25",
    "signal_providers": ["BID001"],
    "location": { "countries": ["USA"] },
    "connectivity_network_kind": "home",
    "connectivity_networks": ["Starlink"]
  }],
  "networkswitching": {
    "network_type": "home",
    "from_month": "2026-09",
    "to_month": "2026-10",
    "min_home_days": 3
  }
}

The weeks in this example only show the format. Send two months whose last full weeks are built. Leave connectivity_networks empty to keep every network of the kind.

Read the results with the same GET /api/v2/analyses/audiences/{id} you poll below. They are in analysis_results.network_switching, which is null until the analysis finishes, and for good if the build fails. The results name the two weeks they compared in from and to, with source connectivity. Their fields are in API Reference - Audiences. A schedule of an audience built with the analysis cannot be created yet.

Poll until Completed

Audience creation is asynchronous (see The Async Model). The create response gives you the new audience id; poll it until its lifecycle status reaches 104 Completed.

curl "https://console.intuizi.com/api/v2/analyses/audiences/<AUDIENCE_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"
  • 100-103, 105, 108, 109 - still processing. Poll again shortly. 109 Visualizing data streams means the audience is drawing the data stream visualizations it opted into, and 105 DataStreaming comes before 104.
  • 104 Completed - the audience is ready to activate.
  • 107 Additional Info - the build stopped and will not continue. Stop polling. Audience Manager shows the reason, most often a date range outside the data available for the dataset. Fix the request and create the audience again.
  • 4xx - an error state. Stop polling and inspect the response.

See List, Get & Delete for reading and removing audiences, and Read an Audience for the full read response.

Next steps

Reference