Skip to content
How to use
Working with Reference Data
.md

Working with Reference Data

Before you can build an audience, you need the ids and values its filters expect - a country code, an IAB category id, a CTV vendor name, an app bundle id, a cohort id, and so on. Reference data is how you fetch those. You read the catalogs first, pick the values you want, then pass them into the audience builder.

What reference data is

Reference data is the set of read-only catalogs that populate the audience builder’s dropdowns. They are exposed under:

GET /api/v2/analyses/reference/*

Each read returns a list you choose from - there is no free typing of internal ids. Catalog reads (countries, IAB, CTV, web, apps, languages) are global, filtered only by your account’s permissions. Your-data reads (cohorts, endpoint connections) return your company’s records; secrets are never included.

These reads sit under analyses because they populate the Audience Manager builder for the Datasets you target. For the complete, field-level list of every reference endpoint - parameters, paging, and exact response fields - see the API Reference. This guide is the narrative; the reference page is the contract.

Authentication

Every reference read is authenticated and JSON-only. Send your bearer token and the JSON Accept header on every request:

curl "https://console.intuizi.com/api/v2/analyses/reference/common/countries" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

A request without Accept: application/json is rejected with 406 Not Acceptable. A missing, invalid, or expired token returns 401. See Authentication and Errors.

The response envelope

Reference reads use the same envelope as the rest of the API - { status, code, message, data }. Simple catalogs return a flat list under data:

{
  "status": "success",
  "code": 200,
  "message": "...",
  "data": [
    { "value": "IAB1", "text": "IAB1 - Arts & Entertainment", "id": 1 }
  ]
}

Large catalogs are paginated - data carries items plus a pagination object, and the reads accept page, per_page, and search query params:

{
  "status": "success",
  "code": 200,
  "message": "...",
  "data": {
    "items": [ { "value": "...", "text": "..." } ],
    "pagination": { "current_page": 1, "per_page": 50, "total": 480, "last_page": 10 }
  }
}

The API Reference marks which reads are paginated and which params each one accepts.

Reference reads by dataset

Pick the dataset you are targeting (see Datasets), then read the catalogs it needs. Use the exact endpoint paths below; the API Reference has the parameters for each.

Web

Web-domain audiences target people by the domains they visit, their device, and their location.

GET /api/v2/analyses/reference/common/countries
GET /api/v2/analyses/reference/common/states          # cascades on a countries param
GET /api/v2/analyses/reference/common/cities          # cascades on a states param
GET /api/v2/analyses/reference/web/iab-categories
GET /api/v2/analyses/reference/web/iab-subcategories
GET /api/v2/analyses/reference/web/domains
GET /api/v2/analyses/reference/web/ref-domains
GET /api/v2/analyses/reference/web/device-types
GET /api/v2/analyses/reference/web/device-makes
GET /api/v2/analyses/reference/web/device-oses
GET /api/v2/analyses/reference/web/browsers
GET /api/v2/analyses/reference/common/languages

Every geo read cascades and the full catalogs are never published. The geo hierarchy is countries -> states -> DMAs -> cities -> zipcodes: request states for the countries you picked, DMAs for those countries/states, cities for the states (optionally narrowed by DMA), and zipcodes for the cities. A request without the required parent parameter returns a 422. ZIP codes on the Web dataset are free text (typed in, not chosen from a catalog); for POI audiences use the common/zipcodes read below.

CTV

Connected-TV audiences target people by the streaming content and devices they use.

GET /api/v2/analyses/reference/ctv/vendors
GET /api/v2/analyses/reference/ctv/content-types
GET /api/v2/analyses/reference/ctv/content-genres
GET /api/v2/analyses/reference/ctv/channel-names
GET /api/v2/analyses/reference/ctv/device-types      # paginated + search
GET /api/v2/analyses/reference/ctv/device-makes      # paginated + search
GET /api/v2/analyses/reference/ctv/device-oses       # paginated + search
GET /api/v2/analyses/reference/ctv/connection-types  # paginated + search
GET /api/v2/analyses/reference/ctv/isps              # paginated + search
GET /api/v2/analyses/reference/ctv/series            # paginated + search

Cohorts

The Cohorts dataset reuses your own saved cohorts as building blocks.

GET /api/v2/analyses/reference/cohorts/get-cohorts          # company-scoped, completed cohorts only

This read returns your company’s completed cohorts.

Apps

Mobile-app audiences target people by the apps they have and the categories those apps belong to.

GET /api/v2/analyses/reference/apps/categories
GET /api/v2/analyses/reference/apps/tags
GET /api/v2/analyses/reference/apps/os
GET /api/v2/analyses/reference/apps/bundle-ids
GET /api/v2/analyses/reference/apps/taxonomies

POI

Points-of-interest audiences target people by the places they physically visited. The POI catalogs cascade - pick segments, then read categories, brands and locations in turn.

GET /api/v2/analyses/reference/poi/segments
GET /api/v2/analyses/reference/poi/categories    # cascades on a segments param
GET /api/v2/analyses/reference/poi/brands        # cascades on a categories param
GET /api/v2/analyses/reference/poi/locations     # cascades on a brands param, paginated
GET /api/v2/analyses/reference/common/dmas       # cascades on a countries param (states/cities narrow)
GET /api/v2/analyses/reference/common/zipcodes   # cascades on a cities param (states/dmas/countries narrow), paginated

POI categories, brands and locations combine Intuizi’s public POI catalog with your company’s own POI data, filtered by your account’s POI permissions.

Affinity Transactions

Purchase audiences (AffinityTransactions), United States only. The purchase catalogs cascade - pick categories, then read sub-categories and brands.

GET /api/v2/analyses/reference/affinity-transactions/categories
GET /api/v2/analyses/reference/affinity-transactions/subcategories   # cascades on a categories param
GET /api/v2/analyses/reference/affinity-transactions/brands          # cascades on categories/subcategories
GET /api/v2/analyses/reference/affinity-transactions/incomes
GET /api/v2/analyses/reference/affinity-transactions/ages
GET /api/v2/analyses/reference/affinity-transactions/genders
GET /api/v2/analyses/reference/affinity-transactions/ethnicities

Demographics

Household-demographic audiences (Demographics). Four flat dictionaries, no cascade.

GET /api/v2/analyses/reference/demographics/genders
GET /api/v2/analyses/reference/demographics/ages
GET /api/v2/analyses/reference/demographics/marital-statuses
GET /api/v2/analyses/reference/demographics/incomes

Deidentified

Delivers the deidentified signals themselves (Deidentified) for a country and date window. One flat field catalog, grouped by field group.

GET /api/v2/analyses/reference/deidentified/fields

Profile Attributes

Attribute audiences (ProfileAttributes). The attribute catalogs cascade, plus a read for the delivered quarter window the dates are bounded to.

GET /api/v2/analyses/reference/profile-attributes/categories
GET /api/v2/analyses/reference/profile-attributes/keys            # cascades on a category_ids param
GET /api/v2/analyses/reference/profile-attributes/values          # cascades on category_ids + key
GET /api/v2/analyses/reference/profile-attributes/recency-limits  # the delivered quarter window

Origin

Home-location audiences (Origin) have no catalog of their own - every filter is a common geography value. Read the countries with datasetType=Origin to get only the ones the dataset covers, then cascade as for POI.

GET /api/v2/analyses/reference/common/signal-providers?dataType=Origin
GET /api/v2/analyses/reference/common/countries?datasetType=Origin
GET /api/v2/analyses/reference/common/states      # cascades on a countries param
GET /api/v2/analyses/reference/common/cities      # cascades on a states param
GET /api/v2/analyses/reference/common/dmas        # cascades on a countries param
GET /api/v2/analyses/reference/common/zipcodes    # cascades on a cities param, paginated

Shared and activation reference reads

A few reads apply across datasets or are used when you later activate an audience to an endpoint:

GET /api/v2/analyses/reference/common/signal-providers
GET /api/v2/analyses/reference/common/endpoint-partners       # company-scoped
GET /api/v2/analyses/reference/common/pricing-models
GET /api/v2/analyses/reference/common/endpoint-connections    # company-scoped, secret-free
GET /api/v2/analyses/reference/common/datastreams
endpoint-connections returns only { id, name, partner: { id, name, inputs } } - partner credentials and stored connection values are never present in any reference read.

pricing-models and datastreams both take the partner_id of the connection you picked, so read the connection first. Deliver to a Partner Endpoint walks through that order and shows how partner.inputs maps onto the activation request.

Putting it together

  1. Authenticate and get a bearer token (Authentication).
  2. Decide which dataset you are building.
  3. Read the reference catalogs that dataset needs (above), paging and searching the large ones as needed.
  4. Collect the value/id of each filter you want.
  5. Use those values to build your audience - see Create an Audience.
  6. Once it is Completed, activate it to an endpoint connection.

Related

  • Datasets - the datasets an audience can target and the filters each one supports.
  • Create an Audience - build an audience from the values you collected here.
  • Common and Dataset Types - the field-level reference for every catalog read.
  • Limits & Quotas - pagination defaults and caps for the reference reads.
Create an Audience