browse_poi_data
ChatGPTRead the caller's POI data (GET /api/v2/my-data/pois/...). kind selects the collection: segments, categories, brands, pois, submissions. Pass id for a single record (pois and submissions only). Extra arguments become query parameters (search, page, per_page where supported).
cancel_lookalike
ChatGPTRequest cooperative cancellation of an in-flight Lookalike Model run (POST /api/v2/analyses/audiences/cancel-lookalike). The worker stops at its next progress checkpoint; a finished run returns an error.
create_activation
ChatGPTActivate a Completed audience to a partner endpoint connection (POST /api/v2/analyses/activations/create). Body fields exactly as documented at https://console.intuizi.com/developers/api/v2/activations. Discover endpoint_connection_id via lookup_reference endpoint-connections, then pricing-models and datastreams (both need that connection's partner_id). The audience must be Completed first (get_audience data[0].status.id = 104). FREQUENCY FILTER: freq_min / freq_max only apply when freq_limit is true, and are REJECTED (422) when sent without an explicit freq_limit - never applied implicitly. To activate a previewed range, send the same freq_min / freq_max as preview_activation with freq_limit=true and its filter_hash; the server recomputes the hash and rejects any mismatch (different range, or an audience rebuilt since the preview). The response echoes filters and filter_hash.
create_audience
ChatGPTCreate an audience (POST /api/v2/analyses/audiences/create). The datasets array holds one or two dataset blocks EXACTLY as documented at https://console.intuizi.com/developers/api/v2/audiences - discover valid filter values via lookup_reference first. A key a dataset type does not define (a misspelling, another type's key, or a filter the type lacks - Deidentified has NO device/OS filter, its fields object only selects output columns) is rejected with 422 naming the key; fix the payload rather than retrying. Poll get_audience until data[0].status.id is 104 (Completed). Writable dataset types: POI, WebDomain, CTV, Apps, Cohorts, AffinityTransactions, Demographics, Deidentified, ProfileAttributes, Origin. A POI block (store visitation) REQUIRES start_date, end_date, signal_providers and location.countries, plus at least one of categories, analysisdata or locations. The BRAND field is called analysisdata - a flat list of POI brand ids from lookup_reference(dataset="poi", catalog="brands"). There is no "brands" key on this type and brands are NEVER nested inside categories: categories is a flat list of integer POI category ids from lookup_reference(dataset="poi", catalog="categories"), and an object there is rejected with 422. Geography goes on the block as location.countries / location.states / location.cities / location.zipcodes (the poi/locations catalog also takes states and cities to narrow the list it returns). So "Ford dealerships in California last week" is {"type":"POI","analysisdata":[<Ford brand id>],"location":{"countries":["USA"],"states":["CA"]},...}. The type the console labels "Transactions" is AffinityTransactions - purchase-affinity data, United States only. Its block REQUIRES start_date, end_date and signal_providers (the common fields every type except Cohorts and Demographics carries) plus at least one of categories (affinity category ids) or brands (affinity brand id strings). Optional: subcategories (MCC description strings), incomes, ages, genders, ethnicities, channels ("B&M" and/or "ONLINE"), spend_min, spend_max, txn_min, txn_max, analysis_spend_frequency, analysis_transactions_frequency, max_devices_per_ip (1-5, default 3), and location.states / location.cities / location.zipcodes (location.countries is optional and always stored as ["USA"]; location.dmas is rejected). end_date cannot run past the most recent fully-settled purchase week. Resolve categories, subcategories, brands, incomes, ages, genders and ethnicities with lookup_reference(dataset="affinity-transactions", ...); signal_providers with lookup_reference(dataset="common", catalog="signal-providers", dataType="AffinityTransactions"); and the geo arrays from the common states / cities / zipcodes catalogs. The earlier "Transactions" dataset (merchants / spend / frequency bands) is retired and rejected here. A WebDomain block's start_date must fall within the last 45 days of available web data - older visitation data is archived and rejected. A ProfileAttributes block REQUIRES start_date, end_date, signal_providers and profile_attributes: a list of {category_id, key, value_ids} rows AND-ed together. Note the field is value_ids (integer ids), NOT values (raw strings) - resolve them with lookup_reference(dataset="profile-attributes", catalog="values", key="<key>"), whose items carry the id in "value" and the underlying data in "raw_value"; resolve category_id and key with the sibling "categories" and "keys" catalogs. Dates are QUARTER-ALIGNED and must fall inside the delivered window returned by lookup_reference(dataset="profile-attributes", catalog="recency-limits"). location is NOT supported for this type - the dataset carries no geography and the builder discards it, so location.countries is optional (accepted for backward compatibility, never applied) and states / cities / zipcodes / dmas are rejected. An Origin block targets devices by their resolved HOME location (where they originate), not by places visited. Its only filters are geographic: it REQUIRES start_date, end_date, signal_providers (from lookup_reference(dataset="common", cat…
create_cohort
ChatGPTCreate a cohort (POST /api/v2/analyses/cohorts/create). Body fields exactly as documented at https://console.intuizi.com/developers/api/v2/cohorts. Two sources: with source "file" (the default) supply exactly ONE of file_uri (a cloud file the caller owns) or upload_reference (from create_upload with purpose cohort, after the file was PUT to the presigned URL) plus identifier_type/identifier_column - use preview_cohort_file first to confirm identifier_column. With source "audience" supply audience_id (a Completed audience the caller owns; a regular audience makes at most one cohort, a Lookalike Model can make several) and a limit: freq_limit with freq_min/freq_max (and optional is_day_part), or distance_limit with distance (meters), or - Lookalike Model audiences only - score_limit with min_score/max_score (0 to 1, band upper bounds of the model score histogram, min at most max; the cohort keeps the best-scored EIDs first, capped by device_limit), or neither for a device limit (optional device_limit). The audience cohort takes its name from the audience.
create_lookalike_audience
ChatGPTBuild a Lookalike Model from a completed seed audience (POST /api/v2/analyses/audiences/create-lookalike). Seed rules: pick a seed from list_audiences whose data[0].status.id is 104, whose is_lookalike is false, and whose results_count is at least 1,000 devices (by default). target_size max 4,000,000 by default. The result is a NEW audience (is_lookalike true) - poll it with get_audience until data[0].status.id is 104. Requires the Lookalike capability on the account; a 403 means it is not enabled.
create_poi_brand
ChatGPTCreate a POI brand (POST /api/v2/my-data/pois/brands/create). Body fields exactly as documented at https://console.intuizi.com/developers/api/v2/poi.
create_poi_category
ChatGPTCreate a POI category (POST /api/v2/my-data/pois/categories/create). Body fields exactly as documented at https://console.intuizi.com/developers/api/v2/poi.
create_poi_submission
ChatGPTSubmit POIs as an inline list (POST /api/v2/my-data/pois/submissions/create-by-list). Body fields exactly as documented at https://console.intuizi.com/developers/api/v2/poi. For file-based submissions, reserve an upload with create_upload (purpose poi_submission), have the file PUT to the presigned URL, then call the raw API endpoint create-by-upload with the upload_reference.
create_project
ChatGPTCreate a project for the caller company (POST /api/v2/analyses/projects/create). Returns the new project id to pass as project_id on an audience, activation or cohort create. Body fields exactly as documented at https://console.intuizi.com/developers/api/v2/projects.
create_upload
ChatGPTReserve an upload slot (POST /api/v2/uploads/create) and receive a presigned single-key PUT URL plus a one-shot upload_reference. IMPORTANT: this tool cannot transfer file bytes itself - hand the returned upload_url to the user (or to a tool that can make an HTTP PUT) so the file is uploaded before its expiry, then pass upload_reference to create_cohort (purpose cohort) or to the POI create-by-upload endpoint (purpose poi_submission). Full contract at https://console.intuizi.com/developers/api/v2/uploads.
delete_activation
ChatGPTPermanently delete an activation owned by the caller company (POST /api/v2/analyses/activations/delete-by-id).
delete_audience
ChatGPTPermanently delete an audience owned by the caller company (POST /api/v2/analyses/audiences/delete-by-id).
delete_cohort
ChatGPTPermanently delete a cohort owned by the caller company (POST /api/v2/analyses/cohorts/delete-by-id).
delete_poi_submission
ChatGPTPermanently delete a POI submission owned by the caller company (POST /api/v2/my-data/pois/submissions/delete-by-id).
estimate_audience_size
ChatGPTRead-only size estimate for the audience a payload WOULD create (POST /api/v2/analyses/audiences/estimate). Takes the EXACT same body as create_audience (name, datasets, optional operator) - including the same 422 on any dataset key the type does not define - and runs the same build pipeline, so the numbers match what create_audience would produce - but NO audience is created, nothing appears in the Audience Manager, and no export, cohort, schedule, or activation side effect can fire. Asynchronous and roughly as slow (and as costly) as a real build - the scan counts toward the company's monthly data-scan limit like a build (operation type "estimate" on get_usage) and is refused with the same 422 once the limit is reached: poll get_audience_estimate until status is completed, blocked, or failed. The response carries recipe_hash - a canonical hash of the datasets+operator recipe. Calling create_audience with the identical payload stamps the SAME hash on the new audience (visible via get_audience), proving the created audience matches the estimated recipe. Estimating never creates anything: always confirm with the user before a follow-up create_audience.
get_activation
ChatGPTFetch one activation with its delivery status (GET /api/v2/analyses/activations/{id}). The response data is a one-element array: poll until data[0].status.id is 104 (Completed). Delivered audience data lands at the destination configured on the endpoint connection; the API does not return a delivery URI.
get_audience
ChatGPTFetch one audience with its lifecycle status (GET /api/v2/analyses/audiences/{id}). The response data is a one-element array: poll until data[0].status.id is 104 (Completed, the only terminal success state); 105 means results are still streaming in. To follow an audience to what it was built from, use ids, never names: a lookalike names its seed in source_audience, and a Cohorts dataset entry names its cohort in dataset[].cohort (then get_cohort). A null reference means the resource was deleted or belongs to another company.
get_audience_estimate
ChatGPTFetch one size estimate with its status and numbers (GET /api/v2/analyses/audiences/estimate/{id}). Poll until data[0].status is completed, blocked, or failed. On completed, data[0].estimate holds uniques (approx_distinct device count, ~2.3% standard error - the same method real audience totals use), visits/signals where the dataset types carry them, provider coverage, as_of, the runtime/cost query_metrics, and the echoed canonical recipe_hash. On blocked, data[0].estimate.blocked is {code, reason} explaining why no number is available (e.g. OUT_OF_COVERAGE with the available date window) - fix the payload and estimate again.
get_cohort
ChatGPTFetch one cohort with its processing status (GET /api/v2/analyses/cohorts/{id}). source says how it was created (file, audience or pixel); source_audience names the audience it was built from (then get_audience), and is null for file and pixel cohorts and for cohorts whose origin was not recorded.
get_cohort_file_scan
ChatGPTFetch one cohort file scan with its status and row counts (GET /api/v2/analyses/cohorts/scan/{id}). While data[0].status.id is 2 (Initiating) or 3 (Processing) the scan is still counting: a scan stages the whole file and usually takes under a minute, so call get_cohort_file_scan again, and if it is still running after about 10 calls, stop, tell the user the scan is still running, give them the id, and read it again later. At 4 (Completed): data[0].total_rows is the number of data rows of the whole file, and data[0].combinations lists each combination of values of data[0].columns with its row count ({values, rows}, values in the order of columns, an empty cell as "", most rows first, at most 1,000). The rows a value keeps are the sum of rows over the combinations that hold it. data[0].truncated true means more combinations existed and the counts are incomplete: say so. At 5 (Not Available): data[0].message says why the file could not be counted (for example a single-column file, or a column the file does not have). The counts are rows, not identifiers: two rows can hold the same identifier. Show the counts to the user and let them choose the values before create_cohort with row_filters.
get_usage
ChatGPTGet the caller company's data-scan usage for a calendar month (GET /api/v2/usage): total bytes scanned, a per-operation-type breakdown, and the monthly limit block (limit, used, percent, enforced/over). Read-only; takes an optional yearmonth (YYYY-MM, defaults to the current month) and always reports the caller's own company. For a past month the limit is still echoed but over_limit / percent_used come back null.
list_activations
ChatGPTList the activations owned by the caller company (GET /api/v2/analyses/activations/index). Supports search, page, per_page.
list_audiences
ChatGPTList the audiences owned by the caller company (GET /api/v2/analyses/audiences/index). Supports search (name filter), page, per_page.
list_cohorts
ChatGPTList the cohorts owned by the caller company (GET /api/v2/analyses/cohorts/index). Supports search, page, per_page.
list_projects
ChatGPTList the projects owned by the caller company (GET /api/v2/analyses/projects/index). A project is the folder an audience, activation or cohort is filed under - use this to resolve a project name to the project_id those creates accept. Supports search, page, per_page.
lookup_reference
ChatGPTRead a reference catalog from the Intuizi API (GET /api/v2/analyses/reference/{dataset}/{catalog}). Valid dataset/catalog pairs - common: countries, states, cities, languages, signal-providers, dataset-types, operators, endpoint-partners, endpoint-connections, pricing-models, datastreams, datastream-visualizations, dmas, zipcodes; web: iab-categories, iab-subcategories, domains, ref-domains, device-types, device-makes, device-oses, browsers; ctv: vendors, content-types, content-genres, channel-names, device-types, device-makes, device-oses, connection-types, isps, series; apps: categories, tags, os, bundle-ids, taxonomies; cohorts: get-cohorts; poi: segments, categories, brands, locations; affinity-transactions: categories, subcategories, brands, incomes, ages, genders, ethnicities; demographics: genders, ages, marital-statuses, incomes; deidentified: fields; profile-attributes: categories, keys, values, recency-limits. Extra arguments become query parameters: most catalogs support "search" (free-text label filter), large ones support "page"/"per_page". Required extras: signal-providers needs dataType (a value from dataset-types); pricing-models and datastreams need partner_id (from endpoint-connections); each pricing-models and datastreams item carries dataset_types, and create_activation rejects a pricing model or a stream for none of the audience's dataset types. Note that "datastreams" and "datastream-visualizations" are different things: datastreams are the delivery outputs of an endpoint partner, while datastream-visualizations are the charts an audience can generate as it builds - pass dataset_type to get the ones valid for a given dataset, and use their ids in create_audience datastreams[]. Naming note: the dataset the Intuizi console labels "Transactions" is "affinity-transactions" here (its create_audience type is "AffinityTransactions"); there is no "transactions" group. Start any workflow here - never invent ids.
preview_activation
ChatGPTRead-only dry run of the frequency filter an activation would apply (GET /api/v2/analyses/activations/preview). Returns the EXACT device count the Audience Manager shows as "Limit Audience" for the same Freq. Range: the audience's stored frequency histogram (distinct visit days -> devices) summed over the inclusive [freq_min, freq_max] range - the same predicate the export applies - plus the histogram itself, frequency_bounds (the valid min/max), source_count (the audience total, approximate) vs histogram_total (exact), the read-only recency window, the audience eligibility, as_of and a canonical filter_hash. NOTHING is created, queued, exported, scheduled or billed - call it as often as needed (e.g. once per candidate range). Requires a Completed audience (data[0].status.id = 104) that was built with the Frequency analysis (POI, Apps or WebDomain); any other audience, a day-part frequency, or a range outside frequency_bounds is refused with 422 - never approximated. Recency is NOT an input (it is fixed by the audience definition); any field other than the three below is rejected. To activate exactly what was previewed, call create_activation with the same audience_id, freq_min, freq_max, freq_limit=true and the returned filter_hash unchanged.
preview_cohort_file
ChatGPTRead a bounded prefix (~64 KB) of a cohort source file (POST /api/v2/analyses/cohorts/preview) and return {columns, samples, sample_rows}. Call it BEFORE create_cohort to confirm identifier_column - it takes the same file_uri or upload_reference the create takes (exactly one of the two), plus optional file_format (csv or gzip).
scan_cohort_file
ChatGPTCount the rows of a cohort source file by the values of 1 to 5 of its columns (POST /api/v2/analyses/cohorts/scan), BEFORE create_cohort with row_filters, so the user sees how many rows each value keeps and picks the values from real counts. Takes the same file_uri or upload_reference as preview_cohort_file (exactly one of the two; scanning does not consume the reference), file_format (csv or gzip: a parquet file cannot be filtered), identifier_column (the one create_cohort will use) and columns (column names exactly as preview_cohort_file returns them, never the identifier column). Answers at once with data[0].id at data[0].status.id 2 (Initiating): then call get_cohort_file_scan with that id. Nothing is created but the scan, which is kept for 24 hours. An organization runs at most a few scans at once: a 429 means wait for one to finish. Requires the Cohorts capability on the account, as create_cohort does: a 403 means it is not enabled.