Skip to content

Audiences

Build, list, read and delete custom audiences. Audience creation is asynchronous: the create call returns immediately with a new id, and you poll the get endpoint until the audience reaches its completed lifecycle status. To run a completed audience on a recurring data window - rebuilt and optionally re-exported every cycle - see Schedules.

All audience endpoints are authenticated and JSON-only. Send Authorization: Bearer <token> and Accept: application/json on every call (plus Content-Type: application/json on the POST create). Reads use the read rate bucket (120 requests/min per caller); the create and delete use the write bucket (30 requests/min per caller).

Create Audience

POST /api/v2/analyses/audiences/create

Creates a custom audience for the authenticated user’s company from one or two datasets. Two datasets are combined with an operator. An optional crossvisitation block narrows the audience to people who visited selected points of interest; an optional crosspurchase block runs the built audience against the Transactions purchase data. An optional networkswitching block compares the home network of the audience’s devices in two months. The audience is queued asynchronously; poll GET /api/v2/analyses/audiences/{id} for its status and results_count.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min). Optional: Idempotency-Key header (see below).

The build counts toward your company’s monthly data-scan limit (see Usage). When the limit has been reached and is enforced, the call is refused with a 422 whose message names the limit and the date it resets, before anything is created or queued.

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).
crossvisitationobjectNoOptional POI crossvisitation analysis. Permission-gated - see below.
crosspurchaseobjectNoOptional cross purchase analysis run on the built audience. Permission-gated - see below.
networkswitchingobjectNoOptional Network Switching analysis run on the built audience: it counts the devices that kept, changed, and switched their home network between two months. Permission-gated - see below. The results are read in analysis_results of Get Audience.
analysesobjectNoThe frequency analyses to run as the audience builds - frequency (with its frequency_day_part sub-option), apps_frequency and web_frequency, all booleans - the same toggles as the Audience Manager and what the activation preview depends on. Permission-gated, each tied to its dataset type - see below.
datastreamsobject[]NoData stream visualizations to generate as the audience builds - see below.

An audience holds one or two datasets. A single dataset takes no operator; two datasets require an operator (AND, OR, or NOTIN). Each dataset is validated and company-scoped identically. A second dataset that is present but missing its type is rejected with 422.

Each datasets[i] block always carries a type, and (except for Cohorts and Demographics) a start_date and end_date. The remaining fields depend on the type. The type is one of the dataset types your company is entitled to, fetchable from GET /api/v2/analyses/reference/common/dataset-types.

Common to each datasets[i]:

FieldTypeRequiredDescription
typestringYesThe dataset type. Fetch the types your company is entitled to from GET /api/v2/analyses/reference/common/dataset-types - a type not enabled for your account is rejected with 422.
start_datestring (Y-m-d)Yes for all except Cohorts and DemographicsWindow start date.
end_datestring (Y-m-d)Yes for all except Cohorts and DemographicsWindow 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, AffinityTransactions, ProfileAttributes and SKUs){ countries[], states[], cities[], dmas[], zipcodes[] } (string arrays). countries come from GET .../reference/common/countries; states cascade via GET .../reference/common/states; cities cascade via GET .../reference/common/cities; dmas (POI, Origin and Connectivity only) come from GET .../reference/common/dmas.

Every key in a dataset block must be one the block’s type defines (the common keys above plus the type’s own fields below). Any other key - a misspelling, a key from another type, or a filter the type does not have - is rejected with 422 naming the key, never silently ignored. The same applies inside location.

WebDomain fields:

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 .../reference/web/iab-categories (and .../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 .../reference/web/domains; a domain outside the catalog is rejected with 422.
web_ref_domainsstring[]NoReferrer domains to target. Fetch valid values from GET .../reference/web/ref-domains.
device_typesstring[]NoWeb device type names. Fetch valid values from GET .../reference/web/device-types.
device_makesstring[]NoWeb device make names. Fetch valid values from GET .../reference/web/device-makes.
device_osesstring[]NoWeb device OS names. Fetch valid values from GET .../reference/web/device-oses.
browsersstring[]NoWeb browser names. Fetch valid values from GET .../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).

CTV fields:

FieldTypeRequiredDescription
ctv_vendor_namesstring[]NoCTV vendor names. Fetch valid values from GET .../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 .../reference/ctv/content-genres.
ctv_channel_namesstring[]NoCTV channel names. Fetch valid values from GET .../reference/ctv/channel-names.
iab_codesarrayNoIAB codes. Fetch valid values from GET .../reference/web/iab-categories.
ctv_device_typesstring[]NoCTV device type names. Fetch valid values from GET .../reference/ctv/device-types.
ctv_device_makesstring[]NoCTV device make names. Fetch valid values from GET .../reference/ctv/device-makes.
ctv_device_osesstring[]NoCTV device OS names. Fetch valid values from GET .../reference/ctv/device-oses.
ctv_connection_typesstring[]NoCTV connection type names. Fetch valid values from GET .../reference/ctv/connection-types.
ctv_ispsstring[]NoCTV ISP names. Fetch valid values from GET .../reference/ctv/isps.
ctv_seriesstring[]NoCTV series names. Fetch valid values from GET .../reference/ctv/series.

Cohorts fields:

FieldTypeRequiredDescription
cohort_idintegerYesA completed cohort id owned by your company. Fetch valid ids from GET .../reference/cohorts/get-cohorts, or create one from your own cloud file via Create Cohort. (No dates or location.)

Apps fields:

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

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

POI fields:

Targets people by the points of interest they physically visited. A POI dataset picks its places in one of two modes, set by poi_selection_mode: by categories, brands and locations (categorization, the default), or by the attributes scheduled at locations (attributes, see POI attributes). The POI catalogs cascade: segments -> categories (?segments[]) -> brands (?categories[]) -> locations (?brands[]). Unknown POI category, brand and location ids are rejected with 422, and so is a location whose brand is not available to your company.

FieldTypeRequiredDescription
categoriesinteger[]At least one of categories / analysisdata / locations in categorization mode, absent or empty in attributes modePOI category ids, as a FLAT list of integers ([12, 13]). An object here, such as [{"id": 12, "brands": [3]}], is rejected with 422. Fetch valid values from GET .../reference/poi/categories (cascades from .../poi/segments). With no analysisdata (and no locations to take brands from), each category expands to the brands available to your company; a category with none is rejected with 422.
analysisdatainteger[]At least one of categories / analysisdata / locations in categorization mode, absent or empty in attributes modePOI brand ids. This is the brand field: there is no brands key on a POI block, and brands are never nested inside categories. Fetch valid values from GET .../reference/poi/brands.
locationsarrayAt least one of categories / analysisdata / locations in categorization mode, absent or empty in attributes modePOI location identifiers, interpreted per location_identifier_type. Fetch candidates from GET .../reference/poi/locations.
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.
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 .../reference/poi/attributes and value ids from GET .../reference/poi/attribute-values.
location.countriesstring[]YesCountry codes (at least one). From GET .../reference/common/countries.
location.statesstring[]NoState codes. Cascade via GET .../reference/common/states.
location.citiesstring[]NoCity names. Cascade via GET .../reference/common/cities.
location.dmasstring[]NoDMA market labels. From GET .../reference/common/dmas.
location.zipcodesstring[]NoZIP codes. Cascade from cities via GET .../reference/common/zipcodes (paginated).
signal_providersstring[]YesBID values identifying the signal source (at least one). From GET .../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.
time_limitsobjectNo{ process: boolean, start: 0-23, end: 0-23 }. Hour-of-day window applied only when process is true.
day_limitsobjectNo{ process: boolean, days: integer[] }. Day-of-week filter applied only when process is true; days use ISO numbering (1 = Monday .. 7 = Sunday).
distance_limitsobjectNo{ process: boolean, distance: number, unit: "miles" | "kilometers" }. Radius applied only 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.

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 from GET .../reference/poi/attributes, then the value ids of each attribute from GET .../reference/poi/attribute-values, 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"]
}

AffinityTransactions fields:

Targets people by what they actually bought. The purchase catalogs cascade: categories -> sub-categories (?categories[]) -> brands (?categories[], ?subcategories[]). Unknown category, sub-category, brand and demographic values are rejected with 422.

Transactions purchase data is United States only. location.countries is optional here and is always stored as ["USA"]; sending any other country code is rejected with 422, as is location.dmas (the type reads states, cities and postal codes only).

Transactions purchase data lands one week at a time, and a completed week is only fully loaded about eleven days after it ends. end_date therefore cannot run past the most recent fully-settled week - the latest Sunday that is at least 11 days before today (UTC) - and a later date is rejected with 422. This boundary advances by one week automatically each Thursday, so the newest selectable end date moves forward on its own; there is no fixed cut-off to track.

FieldTypeRequiredDescription
categoriesinteger[]At least one of categories / brandsTransactions purchase category ids. Fetch valid values from GET .../reference/affinity-transactions/categories.
brandsstring[]At least one of categories / brandsTransactions brand id strings. Fetch valid values from GET .../reference/affinity-transactions/brands.
subcategoriesstring[]NoSub-category strings (merchant category descriptions) cascading from categories. Fetch valid values from GET .../reference/affinity-transactions/subcategories. Picked without any brands, they are resolved to the brands they cover.
incomesstring[]NoIncome bands. Fetch valid values from GET .../reference/affinity-transactions/incomes.
agesstring[]NoAge bands. Fetch valid values from GET .../reference/affinity-transactions/ages.
gendersstring[]NoGender values. Fetch valid values from GET .../reference/affinity-transactions/genders.
ethnicitiesstring[]NoEthnicity values. Fetch valid values from GET .../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).

An AffinityTransactions dataset block:

{
  "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 fields:

Targets people by their household demographic attributes. The four dictionaries are flat - no cascade - and at least one of them must carry a selection. Unknown values are rejected with 422.

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 on a Demographics dataset is rejected with 422. Its location supports countries only, 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 .../reference/demographics/genders.
agesstring[]At least one of genders / ages / marital_statuses / incomesAge ranges. Fetch valid values from GET .../reference/demographics/ages.
marital_statusesstring[]At least one of genders / ages / marital_statuses / incomesMarital status values. Fetch valid values from GET .../reference/demographics/marital-statuses.
incomesstring[]At least one of genders / ages / marital_statuses / incomesIncome ranges. Fetch valid values from GET .../reference/demographics/incomes.
location.countriesstring[]YesCountry codes (at least one). From GET .../reference/common/countries.

A Demographics dataset block:

{
  "type": "Demographics",
  "genders": ["F"],
  "ages": ["25-34", "35-44"],
  "incomes": ["100k-150k"],
  "location": { "countries": ["USA"] }
}

Deidentified fields:

Delivers the deidentified signals themselves for a country and date window, rather than a targeted device list - so instead of filters it takes fields: which signal fields the delivery carries.

fields selects output columns only. It does not filter rows: there is no device, OS or platform filter on this type (fields.userDetails: ["deviceos"] adds the OS column to the delivery, it does not restrict the delivery to an OS). A filter-shaped key such as deviceos is rejected with 422.

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 .../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; a longer window is rejected with 422.

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 .../reference/deidentified/fields.
signal_providersstring[]YesBID values identifying the signal source (at least one). From GET .../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). From GET .../reference/common/countries.

A Deidentified dataset block. Its dates 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"] }
}

ProfileAttributes fields:

Targets people by the profile attributes they carry. 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. Use it for “all of these, and at least one of those”.

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

location is not applied to this dataset type. Profile attribute data carries no geography, so the builder discards the whole location block. location.countries is therefore optional - it is still accepted, for backward compatibility with integrations written when it was required, but it never filters anything. location.states, location.cities, location.zipcodes and location.dmas are rejected outright.

Profile attribute data is delivered quarterly. start_date and end_date must fall inside the delivered window published by GET .../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 .../reference/profile-attributes/categories.
profile_attributes[].keystringYesAn attribute key under that category. Fetch valid values from GET .../reference/profile-attributes/keys with ?category_ids[].
profile_attributes[].value_idsinteger[]YesValue ids of that key (at least one). Fetch valid values from GET .../reference/profile-attributes/values with ?category_ids[] and ?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). From GET .../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.

A ProfileAttributes dataset block (no location needed):

{
  "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 fields:

Targets people by their home location - where a device originates - rather than by the places it visited. 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 below narrows that resolved home location.

Its only filters are geographic: beyond the common signal_providers, dates and location, it defines no key of its own.

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 .../reference/common/countries?datasetType=Origin; a country outside it is rejected with 422.

FieldTypeRequiredDescription
signal_providersstring[]YesBID values identifying the signal source (at least one). From GET .../reference/common/signal-providers?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. From GET .../reference/common/countries?datasetType=Origin.
location.statesstring[]NoState codes. From GET .../reference/common/states.
location.citiesstring[]NoCity names. From GET .../reference/common/cities.
location.dmasstring[]NoDMA labels exactly as returned by GET .../reference/common/dmas - the label string, never a numeric code.
location.zipcodesstring[]NoZIP codes. From GET .../reference/common/zipcodes.

An Origin dataset block:

{
  "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"]
  }
}

SKUs fields:

Targets the devices seen on the home networks of the purchases of a product brand, or of the purchases from a merchant, online. It 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. SKUs says what the data is.

A block names 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 merchant is that brand bought from that merchant, and a brand with a category is that brand bought in that category. The block takes no signal_providers, and its location reads countries and states only.

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: the value of the items of Get SKUs Merchants. At most 1,000 distinct keys. A key outside the catalog is rejected with 422 naming it.
brandsstring[]One of merchants / brands / categoriesProduct brand keys: the value of the items of Get SKUs Brands. At most 1,000 distinct keys. A key outside the catalog is rejected with 422 naming it.
categoriesinteger[]One of merchants / brands / categoriesCategory ids: the value of the items of Get SKUs Categories. A category selects itself and every category under it. At most 1,000 distinct ids. An id outside the tree is rejected with 422 naming it.
device_types, device_oses, device_makes, device_modelsstring[]NoThe device of the purchase click, values from Get SKUs Device Values (field type, os, make, model), matched exactly. The audience is still every device seen on that home network.
max_devices_per_ipintegerNoMatch Strictness: how closely a device must match the home network of the purchase click. 1 (very strict) to 5 (more reach). Defaults to 3 (recommended).
item_price_min, item_price_maxnumberNoPrice of one purchased item in USD, 0 to 1,000,000,000. A filter on each purchase line: lines outside the range are left out. item_price_min must not be above item_price_max. See Spend filters.
spend_min, spend_maxnumberNoWhat a home network spent across its matched purchase lines in the window, in USD, 0 to 1,000,000,000. spend_min must not be above spend_max.
orders_min, orders_maxintegerNoThe orders of that home network in the window (orders with a matched purchase line), whole numbers from 1 to 1,000,000. orders_min must not be above orders_max.
spend_top_percentintegerNo50, 25, 10, 5 or 1: rank every home network with a matched purchase by spend and keep the top share. Ties at the cut are kept.
location.countriesstring[]NoCountry codes. From GET .../reference/common/countries. Left out, the purchases of every country are read.
location.statesstring[]NoState codes. From GET .../reference/common/states.

A SKUs dataset block:

{
  "type": "SKUs",
  "start_date": "2026-10-01",
  "end_date": "2026-10-31",
  "merchants": ["example outdoor store"],
  "brands": ["dove", "dove men+care"],
  "location": { "countries": ["USA"], "states": ["TX", "CA"] },
  "max_devices_per_ip": 3
}

The spend filters (item_price_*, spend_*, orders_*, spend_top_percent) select home networks by what they bought (item_price_* filters the purchase lines before anything is counted), and the other dataset types refuse them with 422, except that spend_min and spend_max keep their own meaning on AffinityTransactions. Spend filters defines each one. Each pair is refused with 422 when its minimum is above its maximum. The lists of merchants, brands and device values share a size budget, which is halved when a spend, orders or top spenders key is set; a list that is too long is refused with 422 and asks for fewer keys.

A SKUs audience reads uniques, avg_uniques, orders, orders_per_unique, unique_brands and unique_merchants in its totals.

Connectivity fields:

Targets devices by the network they used: the home internet network (an ISP brand and its technology) or the mobile carrier a device was on for most days of a week. It is available on request, and it covers the United States. Its data is weekly, so the dates are 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.

Every signal source you pick must have data in at least one week of the window. When you set a home area (states, cities, dmas or zipcodes), each source must also feed Origin. The area narrows the devices to those whose Origin home of the same week is in it. Connectivity counts devices, and it does not link a device across signal sources.

FieldTypeRequiredDescription
signal_providersstring[]YesBID values identifying the signal source (at least one). From GET .../reference/common/signal-providers?dataType=Connectivity. Each needs data in at least one week of the window, and with a home area each must also feed Origin.
start_datestring (Y-m-d)YesWindow start. Widened back to the Monday of its week, then moved to the oldest built week if it is earlier.
end_datestring (Y-m-d)YesWindow end, on or after start_date. Widened forward to the Sunday of its week, then moved to the newest built week if it is later.
connectivity_network_kindstringYeshome for home internet networks, or mobile for mobile carriers.
connectivity_networksstring[]NoNetwork names from Get Connectivity Networks for the chosen 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. A name outside the catalog of the kind is refused by name.
connectivity_technologiesstring[]NoHome only: Fiber, Cable, DSL, Cable or DSL, Satellite or Fixed wireless. Empty means any technology. Refused on a mobile kind.
connectivity_min_daysintegerNoMinimum days of a week a device must have used the network, 1 to 7. Default 3.
location.countriesstring[]YesCountry codes (at least one) with Connectivity coverage. From GET .../reference/common/countries?datasetType=Connectivity.
location.states / cities / dmas / zipcodesstring[]NoA home area: the devices whose Origin home of the same week is in it. Values as for Origin.

NOT IN is not available with a Connectivity block yet: it is refused with a 422 on operator.

A Connectivity dataset block:

{
  "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"]
}

Refine

The optional per-dataset refine object 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 is available on POI and Apps datasets, and only for single-dataset audiences - a refine block on any other dataset type, or on either dataset of a two-dataset audience, 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 (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.

A refined POI dataset block:

{
  "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

The optional top-level crossvisitation object narrows the audience to people who physically visited selected points of interest (POIs) within a date window and optional time-of-day and distance limits. It sits alongside datasets in the body and is available only when the request contains a POI dataset - a crossvisitation block on any other dataset type is rejected. When the block is present it carries the same requirements as a POI dataset: a date window (start_date / end_date), at least one country, and exactly one category. Like the frequency analyses, it is not available for some dataset combinations (see below).

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 (never silently ignored). Omitting the block entirely requires nothing.

POI id sources. Pick the POI values from the read-only Dataset Types - POI catalogs: categories from GET .../reference/poi/categories, brands from GET .../reference/poi/brands, and locations from GET .../reference/poi/locations. (Creating and managing the underlying POI data itself is the separate My POI Data surface.)

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). With no brands (and no locations to take them from), the category expands to the brands available to your company; a category with none is rejected with 422.
locationsarrayNoPOI location identifiers, interpreted per location_identifier_type.
location_identifier_typestringNoHow locations 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 .../reference/common/countries.
time_limitsobjectNo{ process: boolean, start: 0-23, end: 0-23 }. Hour-of-day window applied only when process is true.
day_limitsobjectNo{ process: boolean, days: integer[] }. Day-of-week filter applied only when process is true; days use ISO numbering (1 = Monday .. 7 = Sunday).
distance_limitsobjectNo{ process: boolean, distance: number, unit: "miles" | "kilometers" }. Radius applied only when process is true.

Frequency analyses

The optional top-level analyses object runs the frequency analyses as the audience builds - the same toggles the Audience Manager offers. Each one stores, for every device in the audience, the number of distinct days it was seen on its dataset:

FieldTypeRequiredDescription
frequencybooleanNotrue runs the Visitation Frequency analysis: distinct days a device was seen at the POI dataset’s points of interest. Requires a POI dataset.
frequency_day_partbooleanNoThe Visitation Frequency by Day part sub-option: true buckets the Visitation Frequency by hour of the day instead of by visit day. Requires frequency: true, and is not available when the request holds an Apps dataset. A day-part audience cannot be previewed (hours are not visit counts); its activation applies the Day Part filter instead.
apps_frequencybooleanNotrue runs the Apps Frequency analysis: distinct days a device used the Apps dataset’s apps. Requires an Apps dataset.
web_frequencybooleanNotrue runs the Web Frequency analysis: distinct days a device visited the WebDomain dataset’s domains. Requires a WebDomain dataset; the activation preview supports it on single-dataset WebDomain audiences.

Send the flavour that matches your dataset when you may later want to activate only the devices seen on a minimum number of days (“2+ visits”). The analysis stores the distinct-day histogram that Preview Activation sums and that the freq_min / freq_max filter of Create Activation applies. An audience built without a frequency analysis cannot be previewed or filtered by frequency, and none can be added after the build. A two-dataset audience may carry more than one flavour, exactly as in the Audience Manager, but the preview only resolves an audience that carries exactly one.

The frequency analyses are a gated feature. They require additional permissions that your Account Manager can enable for your account. If any of them is true and the feature is not enabled, the request is rejected with 403 (never silently ignored). Omitting the object, or sending false, requires nothing.

Each flavour needs its dataset. frequency needs a POI block, apps_frequency an Apps block and web_frequency a WebDomain block: a flavour sent without its dataset is rejected with 422 naming it, and so is frequency_day_part without frequency or next to an Apps block. Any other key under analyses is rejected with 422 naming it.

Some datasets turn an analysis off. Cross visitation, Visitation Frequency and Apps Frequency are not available for some dataset types, or for some combinations of two datasets and an operator. The Audience Manager disables them there, and the API rejects them with 422 on crossvisitation, analyses.frequency or analyses.apps_frequency.

{
  "name": "Coffee shop visitors - January",
  "datasets": [
    {
      "type": "POI",
      "start_date": "2026-01-01",
      "end_date": "2026-01-31",
      "signal_providers": ["BID001"],
      "categories": [101],
      "location": { "countries": ["USA"] }
    }
  ],
  "analyses": { "frequency": true }
}

Data Stream Visualizations

An audience can generate a set of charts while it builds - visitation patterns, dwell time, demographics, CTV and web breakdowns and so on - which are then viewed in the Intuizi console on the audience’s Visualizations tab.

Opt in with the optional top-level datastreams array. It takes the same shape as the one on activations, so a client that already speaks one speaks both:

FieldTypeRequiredDescription
datastreams[].idintegerYesThe data stream id, from the reference catalog below.
datastreams[].visualizing_statusbooleanNotrue to generate this stream’s visualizations. Omitted or false means the stream is listed but not generated.
{
  "name": "Airport visitors - September",
  "datasets": [ { "type": "POI", "start_date": "2026-09-01", "end_date": "2026-09-10" } ],
  "datastreams": [
    { "id": 21, "visualizing_status": true },
    { "id": 14, "visualizing_status": true }
  ]
}

The rendered charts are not returned by this API. There is no endpoint that serves a visualization payload and no PDF export. datastreams controls what gets built, and the results are read in the console. While the charts are drawn, the audience reads 109 Visualizing data streams, before 105 and 104 Completed, so keep polling through it (see Status Codes).

Where the ids come from. List what you may use, scoped to the dataset you are about to build:

GET /api/v2/analyses/reference/common/datastream-visualizations?dataset_type=POI

The list is scoped to the caller: every public stream, plus the private ones assigned to your company. Streams without an active visualization are never listed. Each item carries id, slug, name, dataset_types and visual_count.

Mismatches are rejected, not dropped. A stream that does not apply to this audience’s dataset types is a 422 naming the stream and the types it does support - it is not silently ignored, because a stream built against the wrong dataset produces a broken chart rather than an empty one. An id you are not permitted to use is reported the same way as one that does not exist.

Cross Purchase

The optional top-level crosspurchase object runs the built audience against the Transactions 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 sits alongside datasets in the body. 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: 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 (never silently ignored). Omitting the block entirely requires nothing.

Target value sources. Pick the target values from the read-only Transactions catalogs: target_categories from GET .../reference/affinity-transactions/categories, target_subcategories from GET .../reference/affinity-transactions/subcategories, and target_brands from GET .../reference/affinity-transactions/brands.

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, and cannot run past the most recent fully-settled purchase week - the latest Sunday at least 11 days before today (UTC), which advances each Thursday. A later date is rejected with 422.
target_categoriesinteger[]At least one of target_categories / target_subcategories / target_brandsTransactions category ids to scope the analysis to.
target_subcategoriesstring[]At least one of target_categories / target_subcategories / target_brandsTransactions sub-category strings (verbatim values from the reference read).
target_brandsstring[]At least one of target_categories / target_subcategories / target_brandsTransactions brand id strings.

A crosspurchase block on a request body:

{
  "name": "Coffee visitors vs dining purchases",
  "datasets": [ { "type": "POI", "...": "..." } ],
  "crosspurchase": {
    "start_date": "2025-01-01",
    "end_date": "2025-02-28",
    "target_categories": [1],
    "target_brands": ["501"]
  }
}

Network Switching

The optional top-level networkswitching object 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 sits alongside datasets in the body. The counts are read in analysis_results of Get Audience, and the Audience Manager shows them on the audience’s Analyses tab.

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 the dataset’s signal_providers has data in it, as for the weeks Create Audience accepts for a Connectivity dataset. A month whose last full week is not built is rejected with 422 on networkswitching.from_month or networkswitching.to_month, 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.

A device’s home network in a week is the network it was seen on for the most days, when that is at least min_home_days days. A device has changed when it has a home network in both weeks and the two differ. It has switched when, besides, it did not use its new network in the first week and no longer used its old one in the second. That leaves out devices that use two networks, such as a home and a workplace. A device is compared only with itself inside one signal source, and the counts of the sources are added up. Every count is a count of devices.

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 (never silently ignored). Omitting the block entirely requires nothing.

Any audience that is not one Connectivity dataset is rejected with 422 on networkswitching.

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. A higher number keeps fewer devices, each more certain.

An empty networkswitching object counts as absent. Any other key inside the block is rejected with 422 naming it, never silently ignored. The block cannot be sent together with a crosspurchase block: a body that carries both is rejected with 422, naming crosspurchase.

A networkswitching block on a request body, with the Connectivity dataset it runs on:

{
  "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. The body key is networkswitching, and the key you read the results under is network_switching, in analysis_results.

A schedule of an audience built with the analysis cannot be created yet, and is rejected with 422: a schedule rebuilds its audience every cycle, and the two months must be built weeks.

Collect the ids and values these filters expect from the Dataset Types endpoints first, then pass them in here. Only WebDomain, CTV, POI, Origin and Connectivity read the full location block (POI, Origin and Connectivity also take location.dmas); Apps, Demographics, Deidentified and ProfileAttributes read location.countries only; AffinityTransactions is United States only and reads location.states, location.cities and location.zipcodes; SKUs reads location.countries and location.states, and takes no signal providers; Cohorts takes neither dates nor location, and Demographics takes no dates.

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",
        "signal_providers": ["BID001"],
        "iab_category_codes": [1, 4],
        "web_domains": ["example.com"],
        "device_types": ["Mobile"],
        "browsers": ["Chrome"],
        "languages": ["en"],
        "location": { "countries": ["USA"] }
      }
    ]
  }'

Response

The create response is the freshly queued audience (status Initiating, results_count 0). credits_charged is the credits the build was charged, or null unless your organization is billed in credits. The build’s price is known before you create it, from Quote Audience.

{
  "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,
      "is_lookalike": false,
      "results_count": 0,
      "credits_charged": 4,
      "created_at": "2025-01-01 12:00:00"
    }
  ]
}

Idempotency

The optional Idempotency-Key header makes a create safe to retry. The key is caller-generated: any unique string up to 255 characters (a UUID v4 is typical), one per logical create - reuse it only when retrying that same request. The first request with a given key runs normally and the successful (2xx) response is cached per caller. A retry with the same key and the same body replays the stored response verbatim with an Idempotency-Replayed: true header, so no duplicate audience is created. A retry with the same key but a different body returns 409 Conflict. See Idempotency for the full replay semantics and the eight endpoints that honor the header.

List Audiences

GET /api/v2/analyses/audiences/index

Lists the audiences owned by the authenticated user’s company, most recent first, paginated. An item is the audience as Get Audience returns it, except that it leaves out analysis_results: the results of one audience can be large, so read them with Get Audience.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Query parameters

FieldTypeRequiredDescription
per_pageintegerNoItems per page. Defaults to 25, capped at 100.
pageintegerNoPage number (standard pagination).
searchstringNoOptional free-text filter on the audience name (case-insensitive contains).
curl "https://console.intuizi.com/api/v2/analyses/audiences/index?per_page=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

Response

{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": {
    "items": [
      {
        "id": 88,
        "name": "Coffee Buyers NYC",
        "status": { "id": 104, "name": "Completed" },
        "is_cohort": false,
        "is_lookalike": false,
        "results_count": 482311,
        "credits_charged": null,
        "is_activation_allowed": true,
        "eligibility": {
          "allowed": true,
          "reasons": [],
          "metrics": {"unique_eids": 482311, "unique_scids": null, "eid_scid_ratio": null, "is_affinity": false}
        },
        "totals": {"uniques": 482311, "visits": 1203440, "avg_uniques": 16077, "avg_visits": 40114},
        "source_audience": null,
        "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
        "project": { "id": 4, "name": "Retail 2025" },
        "operator": "AND",
        "dataset": [
          { "analysis_type": "WebDomain", "start_date": "01/01/2025", "end_date": "03/31/2025" },
          { "analysis_type": "Apps", "start_date": "01/01/2025", "end_date": "03/31/2025" }
        ],
        "created_at": "2025-01-01 12:00:00",
        "updated_at": "2025-01-10 09:30:00"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total": 1,
      "last_page": 1
    }
  }
}

Get Audience

GET /api/v2/analyses/audiences/{id}

Retrieves a single audience by id.

The same audience is also readable at GET /api/v2/my-data/audiences/{id} for backward compatibility. The two responses differ by two fields: this /analyses/audiences/{id} read includes the operator field (the two-dataset combination mode) and totals (the flat metric whitelist), while the /my-data/audiences/{id} read has neither - it returns eligibility but not totals. When the build recorded a month of the demographics data, this read also carries demographics_stream_vintage, and dataset[].vintage on a Demographics entry. The /my-data/audiences/{id} read carries neither. This read also carries analysis_results, which neither the /my-data/audiences/{id} read nor List Audiences does.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Path parameters

FieldTypeRequiredDescription
idintegerYesThe audience id to fetch.
curl "https://console.intuizi.com/api/v2/analyses/audiences/88" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

Response

created_by is always an object (empty {} when no creator resolves), never null. is_lookalike is true when this audience is the result of a Lookalike Model run - false for every ordinarily-built audience. is_activation_allowed is the verdict of the activation eligibility engine - the same gates the console UI, the activation endpoints and the scheduler apply:

Gate (reasons[].code)Rule
minimum_devicesat least 500 unique devices (1,000 for lookalike outputs)
affinity_device_coverageaudiences containing AffinityTransactions data: unique EIDs must exceed 2x unique SCIDs
scid_count_unavailableTransactions audience built before SCID totals were stored - duplicate and rebuild it
audience_expireda notice, not a block: standard audiences whose latest dataset end date is older than 90 days cannot be delivered as MAIDs or IPs (mapping keys are retained for 90 days). blocks_identifiers = ["MAID", "IP"]; activation with an EID / SCID / HEM pricing model is allowed, a MAID or IP pricing model is rejected with 422. Transactions, lookalikes and cohorts are exempt

When blocked, eligibility.reasons[] carries the code, a human message, the threshold used and the observed aggregate counts (for Transactions: unique_eids, unique_scids, eid_scid_ratio, required_unique_eids). eligibility.notices[] has the same shape plus blocks_identifiers: rules that only apply to some output identifiers. They leave allowed true; the activation create rejects a pricing model whose identifiers fall in blocks_identifiers. eligibility.metrics always returns unique_eids, unique_scids (null when the audience has no Transactions data), eid_scid_ratio and is_affinity. totals is the same metric whitelist the console shows (keys vary by dataset type, e.g. uniques, scids, transactions, amount, visits, signals, unique_eips). Only aggregates are returned - never raw SCIDs or device identifiers. dataset is a trimmed summary with one entry per dataset block (one or two entries). A Cohorts entry also carries cohort, the cohort it reads. A POI entry built in attributes mode also carries poi_selection_mode and poi_attributes, the attribute pick it was built from, in the shape POI attributes describes. A POI entry built from categories, brands and locations carries neither. A Demographics entry also carries vintage, the monthly vintage it read (YYYY-MM). operator carries the combination mode for a two-dataset audience (AND, OR, or NOTIN), and is null for a single-dataset audience.

demographics_stream_vintage names the month an audience’s demographics data stream reads (YYYY-MM). It is the month the build recorded, so an audience that is not a Demographics audience carries it too, and a Demographics audience shows the same month in dataset[].vintage. The field is read-only. When the build recorded no month, as for an audience made before 2026-10-24, both are absent.

"dataset": [
  { "analysis_type": "Demographics", "start_date": "", "end_date": "", "vintage": "2026-09" }
],
"demographics_stream_vintage": "2026-09",

Two fields say what an audience was built from, so you can follow it by id instead of by name:

  • source_audience - the seed audience a Lookalike Model was built from (the source_audience_id it was created with). null for every other audience.
  • dataset[].cohort - on a Cohorts entry, the cohort it reads. Get Cohort then says how that cohort was created (source) and, for one built from an audience, which audience (source_audience).

Each is { "id", "name" }, or null when the audience or cohort it points to has been deleted or does not belong to your company - so an id you get here is always one you can fetch.

"source_audience": null,
"operator": "AND",
"dataset": [
  { "analysis_type": "Cohorts", "start_date": "", "end_date": "", "cohort": { "id": 42, "name": "Loyalty program members" } },
  { "analysis_type": "CTV", "start_date": "01/27/2026", "end_date": "07/27/2026" }
]

A POI entry in attributes mode:

"dataset": [
  {
    "analysis_type": "POI",
    "start_date": "09/01/2026",
    "end_date": "09/28/2026",
    "poi_selection_mode": "attributes",
    "poi_attributes": [{ "attribute_id": 3, "value_ids": [9] }]
  }
]

The read returns the datasets and operator only. A crossvisitation block or an analyses object sent on create is not echoed back here - they live outside the public dataset shape and do not round-trip on read. The same holds for the networkswitching block, but its results are read, with the settings they were built with, in analysis_results.

credits_charged is the credits the audience’s run was charged, after any refund: a run that fails, is cancelled, or completes with no results reads 0. It is null unless your organization is billed in credits, and for a run from before it was.

recipe_hash and normalized_payload are the canonical recipe stamped at create time: the same hash a prior Estimate Audience Size call returned for the identical payload, and the normalized body it was computed from. Both are null for audiences created in the console UI or before this field existed.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 88,
      "name": "Coffee Buyers NYC",
      "status": { "id": 104, "name": "Completed" },
      "is_cohort": false,
      "is_lookalike": false,
      "results_count": 482311,
      "credits_charged": null,
      "is_activation_allowed": true,
      "eligibility": {
        "allowed": true,
        "reasons": [],
        "metrics": {"unique_eids": 482311, "unique_scids": null, "eid_scid_ratio": null, "is_affinity": false}
      },
      "totals": {"uniques": 482311, "visits": 1203440, "avg_uniques": 16077, "avg_visits": 40114},
      "analysis_results": {},
      "source_audience": null,
      "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
      "project": { "id": 4, "name": "Retail 2025" },
      "operator": "AND",
      "dataset": [
        { "analysis_type": "WebDomain", "start_date": "01/01/2025", "end_date": "03/31/2025" },
        { "analysis_type": "Apps", "start_date": "01/01/2025", "end_date": "03/31/2025" }
      ],
      "recipe_hash": null,
      "normalized_payload": null,
      "created_at": "2025-01-01 12:00:00",
      "updated_at": "2025-01-10 09:30:00"
    }
  ]
}

Analysis results

analysis_results holds the results of the analyses an audience was built with, under the name of each. Get Audience and the data of the audience.completed webhook carry it. List Audiences leaves it out, because the results of one audience can be large: read them with Get Audience. On the reads that carry it, it is always present and it is read-only. Today the one analysis in it is Network Switching, under network_switching:

  • An audience built without a networkswitching block has "analysis_results": {}.
  • An audience built with the block has "analysis_results": { "network_switching": null } until the analysis finishes, and the results after. It stays null if the build fails.

Every count in it is a count of devices.

"analysis_results": {
  "network_switching": {
    "version": 2,
    "source": "connectivity",
    "network_type": "home",
    "min_home_days": 3,
    "min_cell": 10,
    "from": { "month": "2026-09", "start": "2026-09-21", "end": "2026-09-27" },
    "to": { "month": "2026-10", "start": "2026-10-19", "end": "2026-10-25" },
    "devices_from": 1150000,
    "devices_to": 1200000,
    "devices_both": 1000000,
    "changed": 17000,
    "switched": 4000,
    "networks": [
      {
        "network": "Example DSL",
        "start": 800000,
        "stayed": 788000,
        "gained": 5000,
        "gained_switched": 1000,
        "lost": 12000,
        "lost_switched": 3000,
        "net": -2000,
        "top_from": [{ "network": "Example Satellite", "switched": 1000 }],
        "top_to": [{ "network": "Example Satellite", "switched": 3000 }]
      },
      {
        "network": "Example Satellite",
        "start": 200000,
        "stayed": 195000,
        "gained": 12000,
        "gained_switched": 3000,
        "lost": 5000,
        "lost_switched": 1000,
        "net": 2000,
        "top_from": [{ "network": "Example DSL", "switched": 3000 }],
        "top_to": [{ "network": "Example DSL", "switched": 1000 }]
      }
    ],
    "flows": [
      {
        "from": "Example DSL",
        "to": "Example Satellite",
        "devices": 12000,
        "switched": 3000,
        "reverse": 5000,
        "reverse_switched": 1000
      },
      {
        "from": "Example Satellite",
        "to": "Example DSL",
        "devices": 5000,
        "switched": 1000,
        "reverse": 12000,
        "reverse_switched": 3000
      }
    ]
  }
}

The sample has two networks and no others, so its totals add up from its rows. In a real result the rows with fewer than min_cell devices are not listed and the lists have a limit, so the rows can add up to less than a total.

The fields of network_switching:

FieldTypeDescription
versionintegerThe version of this shape: 2.
sourcestringconnectivity: the analysis read the weekly Connectivity data of the audience.
network_typestringhome or mobile, as the audience was built.
min_home_daysintegerThe home network rule the audience was built with.
min_cellintegerThe fewest devices a row needs to be listed. A flow with fewer devices is not listed, and neither is an entry of top_from or top_to with fewer switched devices. A network is listed when its start or its gained reaches min_cell, so a listed network can show a smaller start. The totals below count every device.
from, toobjectThe two weeks it compared: month (YYYY-MM), and start and end (YYYY-MM-DD) of the last full Monday-to-Sunday week of that month.
devices_fromintegerDevices with a home network in the from week.
devices_tointegerDevices with a home network in the to week.
devices_bothintegerDevices with a home network in both weeks. The counts that follow are of these devices.
changedintegerDevices whose two home networks differ.
switchedintegerChanged devices that did not use the new network in the from week and no longer used the old one in the to week.
networksobject[]Up to 100 networks, the largest first by start plus gained. A network is listed when start or gained is min_cell or more.
flowsobject[]Up to 50 ordered pairs of networks, the pair with the most devices first. Each pair has min_cell or more devices.

Each entry of networks:

FieldTypeDescription
networkstringThe network name of Get Connectivity Networks, or Other for a network that is not in that list.
startintegerDevices whose home network in the from week is this network.
stayedintegerDevices on this network in both weeks.
gainedintegerDevices that changed to this network.
gained_switchedintegerOf gained, the devices that switched.
lostintegerDevices that changed away from this network.
lost_switchedintegerOf lost, the devices that switched.
netintegergained_switched minus lost_switched. It is negative when more devices switched away than switched in.
top_fromobject[]Up to 10 networks that devices switched to this network from, the most devices first. Each entry has network and switched, and min_cell or more switched devices.
top_toobject[]Up to 10 networks that devices switched to when they left this network, in the same shape.

Each entry of flows:

FieldTypeDescription
fromstringThe network the devices changed from.
tostringThe network they changed to.
devicesintegerDevices that changed from from to to.
switchedintegerOf devices, the ones that switched.
reverseintegerDevices that changed the other way, from to to from. 0 when that pair has fewer than min_cell devices.
reverse_switchedintegerOf reverse, the ones that switched. 0 when that pair has fewer than min_cell devices.

When devices and reverse of a flow are close, the flow is mostly devices that moved home, not devices that chose another network. When no device has a home network in both weeks, devices_both, changed, and switched are 0 and networks and flows are empty. devices_from and devices_to still count the devices of each week, so they show which week was empty. The audience still reaches 104 Completed.

Estimate Audience Size

POST /api/v2/analyses/audiences/estimate

Answers “how many devices would this audience hold?” without creating an audience. The request body is identical to Create Audience - same fields, same validation, same 422 responses. Nothing appears in the Audience Manager and no export, cohort, schedule, or activation is triggered.

An estimate of one POI dataset at country or state level is usually answered inside this call, from daily sketches of the POI data. So is an estimate of one AffinityTransactions dataset by brands or categories, optionally with states and channels, from daily sketches of the purchase data. So is an estimate of one CTV dataset filtered only by countries, states, and signal providers, optionally with vendors or with up to 8 different channel names, from daily sketches of the CTV data. The 201 then already has status: "completed" and the numbers in estimate, with method sketch and as_of, the time its data was read. This page calls it a fast answer. While the sketches are tried, this call can take up to about 10 seconds. It then answers completed (a fast answer) or pending. For a POI, AffinityTransactions, or CTV dataset a fast answer equals a full estimate run on the same data, and a full estimate run later can differ a little as new data arrives.

A POI estimate that leaves filters out, or sends exactly the default set, can get a fast answer: the sketches hold the numbers of that default set. An estimate with filters: [], or with any other set, is answered by a worker. That is slower, and it counts toward the build budget. A fast answer for an AffinityTransactions dataset gives uniques (devices) and, in totals, scids (persons), brands, categories, first_transaction, and last_transaction. The sketches hold no amounts, so it leaves transactions, amount, online_transactions, and the four ratios (avg_amount_per_scid, avg_transaction_value, avg_transactions_per_scid, and online_share) null, not 0. A full estimate has them. A fast answer for a CTV dataset gives uniques (CTV viewers), signals, and unique_eips (households), and leaves visits and number_of_days null, as a full CTV estimate does.

Every other estimate is answered by a worker, as before: this call answers at once, with status: "pending", and how long the answer takes depends on the datasets. It can take minutes, for example AND, OR, NOTIN, and city, DMA, or ZIP requests. A POI estimate that the sketches cannot answer goes to a worker too. This is the case when its dates reach past the data they hold, when it turns its quality filters off or sends a set other than the default, and when it uses an hour-of-day, day-of-week, or distance limit, a list of locations, refine, or POI attributes. An AffinityTransactions estimate goes to a worker too when its dates reach past the data the sketches hold, or when it uses cities, ZIP codes, incomes, ages, genders, ethnicities, spend_min, spend_max, txn_min, txn_max, a max_devices_per_ip other than 3, or a state with a non-ASCII character. A CTV estimate goes to a worker too when its dates reach past the data the sketches hold, or when it uses cities, ZIP codes, languages, iab_codes, ctv_content_genre_names, ctv_series, ctv_device_types, ctv_device_makes, ctv_device_oses, ctv_connection_types, or ctv_isps. It also goes to a worker when it names vendors and channel names together, more than 8 different channel names, channel names for a window of more than 99 days, or a state, vendor, or channel name with a non-ASCII character.

Read a pending estimate with GET /api/v2/analyses/audiences/estimate/{id} until status is completed, blocked, or failed. Add wait to that read and it waits up to 15 seconds for the answer instead of answering at once.

An estimate is metered on the bytes it scans, which count toward your company’s monthly data-scan limit, reported under the estimate operation type on Usage. When the limit has been reached the call is refused with the same 422 a create receives, before the estimate is queued or answered. A fast answer is metered the same way, on the bytes it reads, and does not count toward the build budget.

When your organization sends a recipe again (the same recipe_hash) while an estimate of it is still running, or within 10 minutes after that run completed, nothing new runs. The call answers with a new estimate, with its own id, name, and project_id, that shares the run of that estimate, and reused_from names it. When that estimate has completed, the new one is completed at once with the same numbers. When it is still running, the new one is pending or processing, like that estimate, and ends as it does: completed, blocked, or failed.

A shared run is not run again. The new estimate is not metered, does not count toward the build budget, and its estimate.query_metrics describe the shared run, so adding up the query_metrics of several estimates that share a run counts that scan more than once. It is still refused with the same 422 once the monthly data-scan limit is reached. An estimate that ended blocked or failed is never shared, and a run is shared only when your request resolves to exactly the same dataset, so a change to the POI catalog in between, for example, starts a new run. A run that is still going more than 15 minutes after its estimate was sent is not shared: the new request runs on its own, metered and counted like any estimate. reused_from is null on an estimate that runs itself.

A fast answer is never shared: the same recipe sent again is usually answered again, often in about a second, and reused_from stays null.

The response carries recipe_hash: a canonical hash of the datasets + operator recipe. Creating an audience with the identical payload stamps the same hash on the audience (returned by Get Audience), proving the created audience matches the estimated recipe. The name and project_id are not part of the hash - renaming does not invalidate an estimate.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min). Optional: Idempotency-Key header (see below).

Body

The body of Create Audience, unchanged: name and datasets required, operator required for two dataset blocks, optional project_id and analyses (checked exactly as on create; an estimate never runs an analysis, and the flags change neither the estimate nor its recipe_hash). Every dataset block rule on this page applies verbatim.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/estimate" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coffee Buyers NYC (probe)",
    "datasets": [{ "type": "Cohorts", "cohort_id": 7 }]
  }'

Response

201 with the new estimate. estimate is null until its run completes, except on a fast answer, which is completed at once and carries its estimate. reused_from is null unless it shares the run of an identical recent estimate.

{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": [
    {
      "id": 12,
      "status": "pending",
      "name": "Coffee Buyers NYC (probe)",
      "recipe_hash": "sha256:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
      "reused_from": null,
      "normalized_payload": {
        "name": "Coffee Buyers NYC (probe)",
        "operator": "Single",
        "datasets": [{ "cohort_id": 7, "type": "Cohorts" }]
      },
      "estimate": null,
      "status_message": null,
      "info": null,
      "project_id": null,
      "created_at": "2026-08-24 12:00:00",
      "updated_at": "2026-08-24 12:00:00"
    }
  ]
}

Get Audience Estimate

GET /api/v2/analyses/audiences/estimate/{id}

Retrieves one size estimate with its status and, once completed, the numbers.

An estimate a worker runs has a status that walks pending -> processing -> one of three terminal states: completed (the estimate object holds the numbers), blocked (the recipe cannot be answered - estimate.blocked is { code, reason }, e.g. OUT_OF_COVERAGE with the available date window), or failed (status_message explains). A fast answer is completed from its first read.

An estimate whose reused_from names another one ends as that one does, with its numbers. A fast answer never shares a run, so its reused_from is null.

With wait, the read waits for the answer: it answers as soon as status is completed, blocked, or failed, and at the latest wait seconds after the request arrived, with the estimate as it is then. A pending or processing answer means the estimate is still running: read it again. At most 5 calls of your organization wait at once (reads with wait and the MCP estimate tools together), and at most 25 across all organizations. Another call answers at once, as it would without wait. Only one call waits per estimate: a newer call for the same estimate takes the wait over, and the older one answers at once. So a read that answers pending well before its wait has passed could not wait: pause before the next read, as you would between polls (for example 5 seconds).

On completed, estimate carries: uniques (approximate distinct device count - the same counting method real audience totals use, with a standard error of about 1.6% when method is sketch or approx_set and about 2.3% when it is approx_distinct), visits / signals / unique_eips where the dataset types produce them, number_of_days (always null on an estimate: where a dataset type has daily averages, they are in totals), the full totals row a create would have shown, providers (signal providers present in the result), as_of (when the numbers were computed, or, on a fast answer, when its data was read), query_metrics (the queries the run took, in the table below), method and exact (how the count was produced), vintage (a Demographics dataset only: the monthly vintage its numbers come from, YYYY-MM), and canonical_hash (the recipe_hash of the estimate). method is sketch for a fast answer, and approx_set or approx_distinct for a full estimate. A fast answer for an AffinityTransactions dataset leaves the amounts of its totals (transactions, amount, online_transactions, and the four ratios) null, not 0.

query_metrics totals the queries that produced the numbers:

FieldTypeDescription
QueryCountintegerHow many queries the run took.
TotalDataScannedBytesintegerThe bytes they scanned. This is the number the estimate is metered on.
TotalExecutionTimeMsintegerTheir execution times added up, in milliseconds.
ByCategoryobjectThe same three numbers for each kind of query, under the name of the kind: DataScannedBytes, ExecutionTimeMs and QueryCount.

info is null, or a sentence about what the number leaves out. When a POI dataset of the recipe is in attributes mode, the estimate does not account for the event time windows of the selected attributes, and the built audience will be materially smaller. See POI attributes.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Path parameters

FieldTypeRequiredDescription
idintegerYesThe estimate id from Estimate Audience Size.

Query parameters

FieldTypeRequiredDescription
waitintegerNoSeconds the read may wait for the answer, from 1 to 15, counted from the moment the request arrives. Any other value is refused (422). Without it, the read answers at once.
curl "https://console.intuizi.com/api/v2/analyses/audiences/estimate/12?wait=15" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 12,
      "status": "completed",
      "name": "Coffee Buyers NYC (probe)",
      "recipe_hash": "sha256:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
      "reused_from": null,
      "normalized_payload": {
        "name": "Coffee Buyers NYC (probe)",
        "operator": "Single",
        "datasets": [{ "cohort_id": 7, "type": "Cohorts" }]
      },
      "estimate": {
        "uniques": 482311,
        "visits": 1203440,
        "signals": null,
        "unique_eips": null,
        "number_of_days": null,
        "method": "approx_distinct",
        "exact": false,
        "as_of": "2026-08-24T12:34:56Z",
        "providers": ["<provider-bid>"],
        "query_metrics": {
          "TotalDataScannedBytes": 11300000000,
          "TotalExecutionTimeMs": 37000,
          "QueryCount": 4,
          "ByCategory": {
            "CreateTable": { "DataScannedBytes": 0, "ExecutionTimeMs": 1000, "QueryCount": 1 },
            "InsertNoHeader": { "DataScannedBytes": 11300000000, "ExecutionTimeMs": 35000, "QueryCount": 1 },
            "SelectNoHeader": { "DataScannedBytes": 0, "ExecutionTimeMs": 1000, "QueryCount": 2 }
          }
        },
        "canonical_hash": "sha256:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
        "totals": { "uniques": 482311, "visits": 1203440 },
        "blocked": null
      },
      "status_message": null,
      "info": null,
      "project_id": null,
      "created_at": "2026-08-24 12:00:00",
      "updated_at": "2026-08-24 12:07:00"
    }
  ]
}

A blocked estimate keeps status: "blocked" and explains itself:

{
  "estimate": {
    "uniques": null,
    "blocked": {
      "code": "OUT_OF_COVERAGE",
      "reason": "No POI signal data is available for 2020-01-01..2020-02-01. POI data is available 2024-01 to 2026-07. Adjust the date range to overlap the available window."
    }
  }
}

Quote Audience

POST /api/v2/analyses/audiences/quote

Returns the price in credits of the audience a payload would create, without creating it. The body is identical to Create Audience, with the same fields, the same validation, and the same 422 responses. Nothing is created, nothing is queued, and the quote is free: it counts toward neither your build budget nor your data-scan limit.

credits is what Create Audience charges for the same payload, as long as the credit rates stay the same. Quote before a create to show the price and the credits left after the run.

Only for an organization billed in credits. Any other organization receives 403 before the body is validated. See Credits.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min).

Body

The body of Create Audience, unchanged. Every dataset block rule on this page applies verbatim.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/quote" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile gamers US",
    "datasets": [{
      "type": "Apps",
      "start_date": "2026-09-01",
      "end_date": "2026-09-30",
      "signal_providers": ["BID001"],
      "categories": [1],
      "location": { "countries": ["USA"] }
    }]
  }'

Response

A month of one Apps category comes to less than one credit, so the audience costs the minimum of 1 and its line carries no credits.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "run_type": "audience",
      "credits": 1,
      "minimum": 1,
      "minimum_applies": true,
      "lines": [
        { "dataset": "Apps", "days": 30, "credits": null }
      ],
      "not_charged": [],
      "available": 4905,
      "available_after": 4904
    }
  ]
}

Response fields

FieldTypeDescription
run_typestringaudience.
creditsintegerThe price of the run in credits.
minimumintegerThe least a run of this type costs.
minimum_appliesbooleantrue when the datasets add up to less than minimum, so the run costs minimum.
linesarrayThe price split over the run’s datasets: dataset (the dataset type, or CrossPurchase for a Cross Purchase), days (the length of its date window, null for a dataset without one), and credits. The credits of the lines add up to the price, and they are null when minimum_applies is true.
not_chargedarrayDataset types of the run that carry no credits.
availableintegerYour organization’s credits now.
available_afterintegerYour organization’s credits after this run.

Delete Audience

POST /api/v2/analyses/audiences/delete-by-id

Soft-deletes an audience and queues the downstream cleanup.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min).

Body

FieldTypeRequiredDescription
idintegerYesThe audience id to delete. Must be owned by your company.
curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/delete-by-id" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "id": 88 }'

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource deleted successfully.",
  "data": []
}

Create Lookalike Audience

POST /api/v2/analyses/audiences/create-lookalike

Builds a Lookalike Model from a completed seed audience. The result is a new audience (is_lookalike: true) that goes through the normal polling lifecycle - poll GET /api/v2/analyses/audiences/{id} for its status. Lookalike Models are a gated feature: accounts without the capability receive 403 - it requires additional permissions which need to be approved by your Account Manager. The seed audience must be a Completed audience owned by your company, must not itself be a lookalike, and must hold at least 1,000 devices by default.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min by default). Optional: Idempotency-Key header (see Idempotency).

Body

FieldTypeRequiredDescription
namestringYesName of the Lookalike Model and its result audience.
source_audience_idintegerYesThe seed audience id this model learns from. Must be owned by your company, Completed, not itself a lookalike, and hold at least 1,000 devices by default.
configobjectYesModel configuration - see the fields below.
config.target_sizeintegerYesHow many devices the output audience should contain. 1 to 4,000,000 by default.
config.geo.countriesstring[]YesCountries the candidate universe is restricted to (at least one). Candidates come from Origin data, which covers only some countries, and the create accepts any country code: a run in which none of the countries has Origin data fails after it is created, and when only some do, the others are left out of the model without an error. Start from the Origin list, GET .../reference/common/countries?datasetType=Origin.
config.geo.statesstring[]NoStates the candidate universe is restricted to.
config.signalsstring[]YesData families the model learns from (at least one): poi, apps, demographics, transactions, profile_attributes. They do not all describe the same thing - see Data families below. (web and ctv are withdrawn; requests naming them are rejected with 422.)
config.exclude_seed_devicesbooleanYesWhen true, the seed audience’s own devices are removed from the output audience.
config.contrast_audience_idintegerNoA second completed audience used as negative examples the model contrasts against. Must belong to your company, be Completed, not be a lookalike, and differ from source_audience_id. Omit for an automatic geo-matched sample.
config.expand_eidsbooleanYesWhen true, each output device is expanded across its linked identifiers.

Data families

The families differ in what they observe and over what period. Both matter when you read a model’s results, so they are worth knowing before you choose.

FamilyWhat it observesGrainWindow
poiPhysical visits to placesDeviceLast full calendar month
appsMobile app usageDeviceLast full calendar month
demographicsAge, income, gender, marital statusDeviceCurrent state, no window
transactionsCard transaction behaviourDeviceOne finalized calendar month
profile_attributesHousehold/person profile of the device’s ONE primary person, read from two catalogs at once: the AA consumer layer (household income and net worth, investments, home ownership, dwelling, education, generation, marital status, household composition, occupation) and the Vision Marketing layer (age band, household size, income band, home ownership and value, education, children, lifestyle flags) - one person per deviceDeviceCurrent state, latest quarterly profile refresh
webWeb browsing (withdrawn; models built before 2026-08-29 still report it)HouseholdTrailing 7 complete days

web is household-derived, which is the one asymmetry to keep in mind. Browsing is observed against a household’s IP address and attributed to the devices in that household, capped at the few devices most associated with the address. A device’s web activity therefore means “browsing seen at this device’s household”, not “browsing done by this device”. Every other family is observed on the device itself.

web also reads a trailing 7 days rather than a calendar month, because browsing is a recency signal. Two families in one model can describe different periods.

Selecting more families is not automatically better. A family only helps when the seed audience’s own devices are covered by it, and coverage varies a great deal between audiences. The completed model reports how much of each cohort each family actually reached, so you can see what a given run drew on.

Reading a completed model back returns a feature_families object recording exactly that:

"feature_families": {
  "registry_version": "2026-08-27.1",
  "included": [
    {
      "name": "web",
      "period": "2026-08-21..2026-08-27",
      "coverage": {
        "seed": 28.85,
        "candidates": 60.2,
        "devices_with_signal": 978047
      }
    }
  ]
}

period is the exact date range the family read, which is what makes a run reproducible for families whose window moves. Families measured over a fixed calendar month omit it - the table above already says what window each family uses.

coverage reports the share of your seed devices and of the candidates (the pool the model scored) that carried the family’s signal. The percentages are the useful part when a model underperforms: a family that reached only a small share of your seed had little to learn from, whatever its coverage of the wider candidate pool. feature_families is null for audiences that are not lookalike models, and for models created before this was recorded.

The read also names the seed the model was built from, so you can read the seed back with Get Audience - for example to see which datasets and date windows it holds:

"is_lookalike": true,
"source_audience": { "id": 14988, "name": "Coffee Buyers NYC" }

| notification | boolean | No | Whether to send an email on completion. Defaults to true. |

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/create-lookalike" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "name": "API Lookalike",
    "source_audience_id": 14988,
    "config": {
      "target_size": 100000,
      "geo": { "countries": ["USA"], "states": [] },
      "signals": ["poi", "apps"],
      "exclude_seed_devices": true,
      "contrast_audience_id": null,
      "expand_eids": false
    }
  }'

Response

The create response is the freshly queued result audience (status Initiating). credits_charged is the credits the run was charged, or null unless your organization is billed in credits. The price is known before you create it, from Quote Lookalike.

{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": [
    {
      "id": 15021,
      "name": "API Lookalike",
      "status": { "id": 100, "name": "Initiating" },
      "is_lookalike": true,
      "source_audience_id": 14988,
      "credits_charged": 120
    }
  ]
}

Cancel Lookalike

POST /api/v2/analyses/audiences/cancel-lookalike

Requests cooperative cancellation of an in-flight Lookalike Model run: the job checks the cancellation flag at its next checkpoint and stops there rather than being killed immediately. A finished run cannot be cancelled. Until the run reaches that checkpoint the audience keeps reading 108 Modeling. When it stops, the audience ends at 400 Error, which is final and never reaches 104, and an audience.failed webhook is sent. Audience Manager shows the status as Cancelled on request. A cancel that arrives once the result is already being published is ignored, and the run completes at 104.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min by default).

Body

FieldTypeRequiredDescription
idintegerYesThe lookalike audience id to cancel - the id returned by Create Lookalike Audience.
curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/cancel-lookalike" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "id": 15021 }'

Response

{
  "status": "success",
  "code": 200,
  "message": "Cancellation requested.",
  "data": []
}

Quote Lookalike

POST /api/v2/analyses/audiences/quote-lookalike

Returns the price in credits of the lookalike a payload would build, without building it. The body is identical to Create Lookalike Audience, with the same validation and the same 403 and 422 responses. A lookalike costs the same for any size. Nothing is created, and the quote is free.

Only for an organization billed in credits. Any other organization receives 403 before the body is validated. See Credits.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min).

Body

The body of Create Lookalike Audience, unchanged.

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/quote-lookalike" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Lookalike",
    "source_audience_id": 14988,
    "config": {
      "target_size": 100000,
      "geo": { "countries": ["USA"] },
      "signals": ["poi", "apps"],
      "exclude_seed_devices": true,
      "expand_eids": false
    }
  }'

Response

The fields of Quote Audience, with run_type lookalike and no lines.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "run_type": "lookalike",
      "credits": 120,
      "minimum": 25,
      "minimum_applies": false,
      "lines": [],
      "not_charged": [],
      "available": 1000,
      "available_after": 880
    }
  ]
}