# 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. {{< callout type="info" >}} These reads sit under `analyses` because they populate the Audience Manager builder for the [Datasets](/concepts/datasets) you target. For the complete, field-level list of every reference endpoint - parameters, paging, and exact response fields - see the [API Reference](/api/v2). This guide is the narrative; the reference page is the contract. {{< /callout >}} ## Authentication Every reference read is authenticated and JSON-only. Send your bearer token and the JSON `Accept` header on every request: ```bash curl "https://console.intuizi.com/api/v2/analyses/reference/common/countries" \ -H "Authorization: Bearer " \ -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](/getting-started/authentication) and [Errors](/concepts/errors). ## The response envelope Reference reads use the same [envelope](/concepts/envelope) as the rest of the API - `{ status, code, message, data }`. Simple catalogs return a flat list under `data`: ```json { "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: ```json { "status": "success", "code": 200, "message": "...", "data": { "items": [ { "value": "...", "text": "..." } ], "pagination": { "current_page": 1, "per_page": 50, "total": 480, "last_page": 10 } } } ``` The [API Reference](/api/v2) marks which reads are paginated and which params each one accepts. ## Reference reads by dataset Pick the dataset you are targeting (see [Datasets](/concepts/datasets)), then read the catalogs it needs. Use the exact endpoint paths below; the [API Reference](/api/v2) 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 ``` {{< callout type="warning" >}} `endpoint-connections` returns only `{ id, name, partner: { id, name, inputs } }` - partner credentials and stored connection values are never present in any reference read. {{< /callout >}} `pricing-models` and `datastreams` both take the `partner_id` of the connection you picked, so read the connection first. [Deliver to a Partner Endpoint](/guides/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](/getting-started/authentication)). 2. Decide which [dataset](/concepts/datasets) 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](/guides/create-an-audience). 6. Once it is Completed, [activate it](/guides/activate-an-audience) to an endpoint connection. ## Related - [Datasets](/concepts/datasets) - the datasets an audience can target and the filters each one supports. - [Create an Audience](/guides/create-an-audience) - build an audience from the values you collected here. - [Common](/api/v2/common) and [Dataset Types](/api/v2/reference) - the field-level reference for every catalog read. - [Limits & Quotas](/concepts/limits) - pagination defaults and caps for the reference reads.