The front door of the API. Resolves an IP address, MAID, or lat/long to a Quorum household ID and returns all MAIDs associated with that household.

Request Body

Response

Example

curl -X POST https://api.quorum.live/v1/resolve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"input_type":"ipv4","value":"73.94.102.215"}'

Returns enrichment data for a specific household: geographic profile, segment visit history, and CTV/OTT publisher exposure. Use the household_id returned by /v1/resolve.

Path Parameters

Response

Example

curl https://api.quorum.live/v1/households/631174766991295487 \
  -H "Authorization: Bearer <token>"

Returns all tracked segments (physical locations) for a given advertiser. Each segment has a unique MD5 identifier used in downstream visit and stats endpoints.

Query Parameters

Response

Array of segment objects. Each contains: segment_md5, location_name, address, city, state, zip, latitude, longitude.

Example

curl "https://api.quorum.live/v1/segments/catalog?advertiser_id=1234" \
  -H "Authorization: Bearer <token>"

Returns per-device visit records for a specific segment (deduplicated). Use for building audience lists or analyzing foot traffic patterns at a specific location.

Path Parameters

Query Parameters

Example

curl "https://api.quorum.live/v1/segments/abc123def456/visits?advertiser_id=1234&days=30" \
  -H "Authorization: Bearer <token>"

Returns 30-day rolling visitor counts per segment for a given advertiser. Useful for quickly identifying which locations are seeing the most traffic without pulling full visit records.

Query Parameters

Response

Array of objects: segment_md5, location_name, visitor_count_30d, device_count_30d.

Example

curl "https://api.quorum.live/v1/segments/stats?advertiser_id=1234" \
  -H "Authorization: Bearer <token>"

Returns all distinct locations a household has visited, enriched with metadata from the Quorum location library. Cross-advertiser — not scoped to a single campaign. Deduplicated on segment MD5 so each physical location appears once with an aggregated visit count.

Path Parameters

Query Parameters

Response

Array of location objects sorted by last_seen descending. Each contains: segment_md5, name, brand, category, dma, zip, visits_30d (library-wide popularity), last_seen (YYYY-MM-DD), visit_days (distinct days this household was observed at this location).

Example

curl "https://api.quorum.live/v1/household/631270081205638655/footprint?limit=50" \
  -H "Authorization: Bearer <token>"

Returns all advertisers available to your agency token. This is the bootstrap call — use it to populate advertiser pickers and to get the advertiser_id values required by all /v1/performance/* endpoints. No legacy Snowflake reads required.

Query Parameters

None. Results are automatically scoped to your agency.

Response

Example

curl "https://api.quorum.live/v1/advertisers" \
  -H "Authorization: Bearer <token>"

Campaign performance broken down by publisher and supply source. Returns daily rows with impressions, device reach, household reach, visitors, visit rate, multiplier, and web metrics per publisher. Primary input for publisher-level optimization and reporting.

Query Parameters

Response

Shared base fields on every PERF row: log_date, io_id, io_name, li_id, li_name, advertiser_id, platform_name, impressions, device_reach, household_reach, visitors, visit_rate, panel_reach, multiplier, web_visitors, total_page_views, web_visit_rate.

Publisher-specific fields: publisher, supply_vendor, publisher_code, site_id, publisher_id, supply_type_id.

Example

curl "https://api.quorum.live/v1/performance/publishers?advertiser_id=1234&date_from=2025-01-01&io_id=IO-456" \
  -H "Authorization: Bearer <token>"

Campaign performance broken down by geography (DMA and ZIP). Returns daily rows with impressions, reach, household reach, visitors, visit rate, and multiplier per geographic unit. Use for regional pacing analysis and DMA-level reporting.

Query Parameters

Response

All shared base fields plus geo-specific: dma, zip, census_block_id.

Example

curl "https://api.quorum.live/v1/performance/geo?advertiser_id=1234&dma=Boston" \
  -H "Authorization: Bearer <token>"

Web pixel performance broken down by traffic source URL. Returns daily rows with impressions, reach, web visitors, and page views per URL. Use for understanding which referral sources and landing pages are driving the most web activity.

Query Parameters

Response

All shared base fields plus traffic-specific: url, url_type.

Example

curl "https://api.quorum.live/v1/performance/traffic?advertiser_id=1234&date_from=2025-03-01" \
  -H "Authorization: Bearer <token>"

Campaign performance broken down by creative unit. Returns daily rows with impressions, reach, visitors, visit rate, and web metrics per creative. Use for A/B analysis and creative rotation reporting.

Query Parameters

Response

All shared base fields plus creative-specific: creative_id, creative_name, creative_size.

Example

curl "https://api.quorum.live/v1/performance/creative?advertiser_id=1234&li_id=LI-789" \
  -H "Authorization: Bearer <token>"

Household-level attribution data. Each row represents a household that received an impression and subsequently visited a tracked location within the 28-day attribution window. The primary input for reach/frequency analysis and household deduplication across line items.

Query Parameters

Response

All shared base fields (note: household_reach is not present on this table — each row IS a household). Plus household-specific: household_id, census_block_id.

Example

curl "https://api.quorum.live/v1/performance/households?advertiser_id=1234&io_id=IO-456&limit=50000" \
  -H "Authorization: Bearer <token>"

Returns the advertiser's capability flags from ADVERTISER_CONFIG — whether they have store attribution, web attribution, the attribution window in days, and report type IDs. Always call this first before any visit-based endpoint so you know what data to expect.

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/config" -H "Authorization: Bearer <token>"

Probes each PERF_BY_* table for data existence in the requested date range and combines with config flags. Use as a gating call before rendering a report UI — avoids rendering empty charts.

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/tab-availability?date_from=2025-10-01&date_to=2025-12-31" \
  -H "Authorization: Bearer <token>"

Headline metrics for an advertiser over a date range. Impressions and reach from PERF_BY_PUBLISHER. Store and web visits from HH attribution tables (last-touch, 28-day window). All visit counts are multiplier-scaled to estimated total reach.

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/summary?date_from=2025-10-01&date_to=2025-12-31" \
  -H "Authorization: Bearer <token>"

Day-by-day impressions and estimated visit counts. Impressions from PERF_BY_PUBLISHER aggregated by LOG_DATE. Visits from HH attribution tables by visit date. Multiplier applied to scale to estimated total. Use to power trend charts.

Response Fields (per day)

Example

curl "https://api.quorum.live/v1/advertisers/1234/timeseries?date_from=2025-10-01&date_to=2025-12-31" \
  -H "Authorization: Bearer <token>"

Performance grouped by insertion order (campaign). Aggregates PERF_BY_PUBLISHER to IO level. Store and web visits joined from HH attribution tables. Coverage multiplier applied per campaign where statistically significant, otherwise advertiser grain.

Response Fields (per campaign)

Example

curl "https://api.quorum.live/v1/advertisers/1234/campaigns?date_from=2025-10-01&date_to=2025-12-31" \
  -H "Authorization: Bearer <token>"

Performance grouped by line item. Aggregates PERF_BY_PUBLISHER to LI level with per-LI coverage multipliers. Provides the finest grain of campaign performance and is the source of truth for visit rate optimization.

Query Parameters

Example

curl "https://api.quorum.live/v1/advertisers/1234/lineitems?date_from=2025-10-01&io_id=IO-456" \
  -H "Authorization: Bearer <token>"

Exposed vs. control visit rate lift. Identifies households exposed to this advertiser's impressions (via HOUSEHOLD_ID_CORE), computes what fraction visited a tracked store or web property within the attribution window, and compares against the non-exposed visiting population. Only available for advertisers with has_store = true.

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/lift?date_from=2025-10-01&date_to=2025-12-31" \
  -H "Authorization: Bearer <token>"

Store visit breakdown by brand and location category. Reads HH_STORE_VISIT_ATTRIBUTION directly (last-touch, 28-day window). Shows which brands within an advertiser's footprint are driving the most visits, and how quickly households convert after seeing an ad.

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/store-visits/brands?date_from=2025-10-01&date_to=2025-12-31" \
  -H "Authorization: Bearer <token>"

Location Attribution & Insights

This endpoint group gives you direct access to Quorum's location intelligence layer — the same data that powers the Optimizer dashboard, exposed as structured API responses you can pipe into your own models, spreadsheets, or activation platforms.

Everything here is scoped to your advertiser's configured locations. Quorum tracks physical visits using a panel of mobile devices and resolves each observed device to a persistent household identity. That resolution unlocks three things you can't get from raw MAID files alone: deduplication at the household level, a high-quality home IPv4 address, and pre-computed geographic trade area profiles.

The Four Endpoints

Typical Workflow

Start with /locations to pull your segment catalog and identify the segment_md5 values you care about. Then call /visits to export raw visit records for audience building or attribution analysis. Use /visitor-geography to understand trade area reach for geo-targeting. Use /nearby-competitors to map the competitive landscape around a specific location.

Privacy & Household IDs

The household_id field in visit records is designed to be useful for matching and deduplication without exposing geographic coordinates. External API callers receive a 32-character HMAC-hashed identifier — stable across calls and consistent for a given household, but not reversible to a lat/lon. Internal Quorum users receive the raw numeric ID. The lowest-granularity geographic field available externally is census_block_id.

Returns all location segments configured for an advertiser — both POI (physical retail/venue) and Attraction (geo-fence zone) types — with full metadata and recent visit volume. This is the starting point for any location workflow: use it to enumerate segment IDs, check coverage, and filter down to the locations you want to analyze.

Segments with zero visits in the 60-day window are included by default. Use min_households=1 to filter to active locations only.

Path Parameters

Query Parameters

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/locations?location_type=POI&min_households=1" \
  -H "Authorization: Bearer <token>"

curl "https://api.quorum.live/v1/advertisers/1234/locations?brand=Chipotle&limit=200" \
  -H "Authorization: Bearer <token>"

Returns raw device visit records for a single location within a date range. Each row represents one device observation at the location's geo-fence, joined to Quorum's identity graph for household resolution and IPv4 enrichment. This is the primary endpoint for bulk audience export and attribution analysis.

Path Parameters

Query Parameters

Response Fields

Example — First Page

curl "https://api.quorum.live/v1/advertisers/1234/locations/abc123def456.../visits?date_from=2025-01-01&date_to=2025-03-31&limit=100000&offset=0" \
  -H "Authorization: Bearer <token>"

Example — Next Page

curl "https://api.quorum.live/v1/advertisers/1234/locations/abc123def456.../visits?date_from=2025-01-01&date_to=2025-03-31&limit=100000&offset=100000" \
  -H "Authorization: Bearer <token>"

Returns a pre-computed trade area profile for a location — a ranked breakdown of home census blocks from which visitors originate, along with visitor index scores that indicate which areas over- or under-index as visitor origins relative to their population size. No date parameters needed: this reads from a 90-day rolling pre-indexed table built by the Quorum pipeline.

This endpoint is ideal for understanding catchment area, planning geo-targeted ad buys, or building audience models that prioritize high-index neighborhoods.

Path Parameters

Response Fields

Example

curl "https://api.quorum.live/v1/advertisers/1234/locations/abc123def456.../visitor-geography" \
  -H "Authorization: Bearer <token>"

Finds all locations in Quorum's reference library that match a category pattern and fall within a configurable radius of your anchor location. Results are ranked by distance (nearest first) and include 60-day household visit counts. Your advertiser's own configured locations are automatically excluded from results.

Use this to map competitive density, compare your traffic footprint against nearby competitors, or identify whitespace in a market.

Path Parameters

Query Parameters

Smart Default Radii

When radius_miles is omitted, the API picks a sensible radius based on keywords in your category_pattern:

Response Fields

Wildcard Examples

Example — All restaurants within 3 miles

curl "https://api.quorum.live/v1/advertisers/1234/locations/abc123def456.../nearby-competitors?category_pattern=restaurant&radius_miles=3" \
  -H "Authorization: Bearer <token>"

Example — Auto dealers (smart default radius of 25 miles)

curl "https://api.quorum.live/v1/advertisers/1234/locations/abc123def456.../nearby-competitors?category_pattern=auto+dealer" \
  -H "Authorization: Bearer <token>"

Error Codes

Data Freshness