Access and scope

A token issued to anyone outside Quorum is a partner token. Partner tokens follow the rules below. Internal Quorum tokens are not affected.

1. You read only your own agency's advertisers

• On the advertiser roll-ups (/v1/advertisers/{advertiser_id}/config, /tab-availability, /summary, /timeseries, /campaigns, /lineitems, /lift, /store-visits/brands), an advertiser that is not your agency's gets 403 with "Advertiser N is not in your agency." Ownership is checked against both of Quorum's advertiser registries. An id that both registries assign to different agencies is refused until Quorum resolves it.
• Routes that take your DSP id (/locations, /visits, /report, /reports) resolve it inside your agency only, or accept a Quorum id your agency owns. Any other id gets 404.
• Routes that filter by your agency (/v1/performance/*, /v1/segments/catalog, /v1/advertisers/{advertiser_id}/segments, /v1/partner-feed/*, /visitor-geography, /nearby-competitors) return an empty list or 404 for an advertiser that is not yours.
• A token can also be limited to a list of advertisers. Any other advertiser_id gets 403.
• If Quorum cannot check ownership at that moment, you get 503, never data. Retry.

2. No device- or household-level routes

These routes return a 403 to partner tokens. The message points to the Quorum MCP at https://mcp.quorum.live/mcp, which answers the same questions as k-anonymous aggregates:

3. Writes need a write-enabled token

POST /v1/intake/* (advertisers, locations, disconnect, reconnect) returns 403 for a read-only token. The qurum_ag_id (or agency_id) in an intake body must equal your token's agency, or the request gets 403.

4. Disconnected advertisers

After you disconnect an advertiser (POST /v1/intake/advertisers/{client_advertiser_id}/disconnect), every read of it returns 410, by your id or by its Quorum advertiser id. Nothing is deleted and capture continues; reconnecting restores everything, including the disconnected period.

Status codes

Errors come back as JSON with a detail field that says what went wrong.

What changed (2026-11-10, API 2.1.0)

• Partner scope. Partner tokens read only their own agency's advertisers, and the device- and household-level routes are refused with 403. See Access and scope.
• Token expiry and read-only tokens. An expired token gets 401; a read-only token gets 403 on POST /v1/intake/*.
• Published report numbers. New GET /v1/advertisers/{advertiser_id}/report and /reports.
• Store status read-back. New GET /v1/intake/locations.
• Disconnect / reconnect. New POST /v1/intake/advertisers/{client_advertiser_id}/disconnect, /reconnect and GET .../connection; reads for a disconnected advertiser return 410.
• Quorum ids on /locations and /visits. A partner token may now pass a Quorum advertiser id its agency owns, not only a DSP id. Useful when your DSP ids are not crosswalked.
• Intake is add-only. Re-posting a store returns the same location_id, with created and status per row. /locations now echoes your client_location_name and location_id.
• Stores move to pending_draw once their advertiser is mapped and they have a usable address.
• One DSP id, several Quorum accounts. /locations and /visits serve the union.
• /visits date window. Dates are UTC days. New opt-in end_exclusive=true for a [date_from, date_to) window; without it date_to is inclusive.
• /locations fields. maid_count_60d is deprecated and always null; use the new device_days_60d. lat, lon, address, city and state are filled, and a stored text 'null' comes back as a JSON null.
• /v1/health works as an alias of /health.
• Removed: the library's free-text question route (ask). Ask open-ended questions through the Quorum MCP.

Every advertiser configured for your agency, with names. The advertiser_id it returns is a Quorum advertiser id; use it on the roll-ups, /v1/performance/*, /v1/segments/* and /v1/partner-feed/*. No parameters.

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

The numbers on your published Quorum report, as data. They come from the same build as the report page, so every figure reconciles with the page. Schema quorum.retail_report.v1.

advertiser_id is your own DSP advertiser id, or a Quorum advertiser id your agency owns. You only ever see reports registered to your agency. A DSP id that is pending, disconnected or ignored answers 202, 410 or 422 as on /locations.

Query parameters

What is in the payload

• headline, daily, weekly, campaigns, publishers, creatives, stores, zips, time_to_visit, plus definitions, windows (with mature and matures_on), attribution_days, kmin and coverage_multiplier. Sections the page does not show are [].
• Visit: one household visiting any of the locations on one calendar day, deduplicated, attributed within attribution_days of an ad exposure. visit_rate = visits / impressions.
• *_det fields are measured (deterministic) households. *_est = *_det × coverage_multiplier.
• The row-level tables carry the measured visits_det. The page shows those cells grossed up, so page value = round(visits_det × coverage_multiplier). Each row's visit_rate is the page's own rate.
• Cells under the reporting floor (k ≥ 3) are null with suppressed: true (or a withheld_reason). The page withholds them too.
• Rates are fractions (0.00096, not 0.096%). Dates are the report's local dates, YYYY-MM-DD.
• publication is added by the API: report_id, version, period, quorum_advertiser_ids, published_at, builder_sha, mature, matures_on, and other_report_ids when the advertiser has more than one report.
• While mature is false, visits can still attribute and the figures can only go up.

404 when there is no published report for the advertiser (and filters). 503 if the stored payload is not in a servable format.

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

Every published version of every report for the advertiser, newest first, without the numbers. Optional period (YYYYMM). Response: {"advertiser_id": ..., "reports": [ {report_id, version, period, quorum_advertiser_ids, published_at, builder_sha, mature, matures_on} ]}.

curl "https://api.quorum.live/v1/advertisers/12345/reports?period=202610" \
  -H "Authorization: Bearer <token>"

The advertiser's capability flags. advertiser_id is a Quorum advertiser id; partner tokens get 403 for an advertiser outside their agency. The same applies to every roll-up below, and each of them takes date_from / date_to (YYYY-MM-DD, default the last 30 days).

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

Which report tabs have data in a date range (date_from, date_to, default the last 30 days). Use it before drawing a report UI.

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

Headline metrics over date_from..date_to. Impressions and reach come from the publisher performance table; visits from the household attribution tables, scaled by a coverage multiplier.

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

One row per day: log_date, impressions, device_reach, household_reach, store_visits, store_visit_rate, web_visits, web_visit_rate. Visits are multiplier-scaled. Params: date_from, date_to.

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

One row per insertion order: io_id, io_name, impressions, device_reach, household_reach, store_panel_reach, store_visits, store_visit_rate, web_panel_reach, web_visits, web_visit_rate, multiplier, first_date, last_date. Params: date_from, date_to.

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

One row per line item, with the same fields as /campaigns plus li_id and li_name. Params: date_from, date_to, and optional io_id to limit to one campaign.

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

Visit rate of exposed households against non-exposed visitors. Params: date_from, date_to.

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

Store visits by brand and category. Response: advertiser_id, total_visits, unique_households, and brands[] with brand, category, visits (measured, not scaled), unique_households, avg_days_to_visit. Params: date_from, date_to.

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

Locations and visits

These routes give you the stores Quorum tracks for an advertiser and the visits it observes there.

Typical workflow

1. POST your advertiser to /v1/intake/advertisers and your stores to /v1/intake/locations.

2. Poll GET /v1/intake/locations until stores are active; each active store lists its segment_md5s.

3. Call /locations to see every tracked location (yours carry your client_location_name).

4. Pull /visits per segment_md5 for a date window.

Polling

/locations and /visits resolve your id first (DSP id, then a Quorum id your agency owns). 200 (even with an empty list) means mapped; 202 means mapped soon, retry; 404 unknown for your agency; 410 disconnected; 422 ignored. Only 202 is a retry signal.

Household ids

The household_id on visit records is, for partner tokens, a stable 32-character HMAC of the household: the same household always gets the same value, so you can deduplicate and match on it, but it cannot be turned back into a location. The finest geography returned is the census block.

Every location configured for the advertiser, both POIs (stores, venues) and Attractions (zones), whether or not visits have been seen. advertiser_id is your own DSP advertiser id, or a Quorum advertiser id your agency owns. Locations with no visits in 60 days are included unless you set min_households.

Query parameters

Response fields

Text fields never carry the string "null": a missing value is a JSON null.

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

Raw visit records for one location: one row per device observation, with household resolution and IP enrichment. advertiser_id is your own DSP advertiser id, or a Quorum advertiser id your agency owns. 404 if the segment_md5 is not configured for the advertiser.

Query parameters

Response fields

curl "https://api.quorum.live/v1/advertisers/12345/locations/abc123def456.../visits?date_from=2026-10-01&date_to=2026-11-01&end_exclusive=true&limit=100000&offset=0" \
  -H "Authorization: Bearer <token>"

Where a location's visitors live, from a pre-built table over a rolling 90-day window. No date parameters. advertiser_id here is the Quorum advertiser id (from GET /v1/advertisers), and the location must be configured for it in your agency, otherwise 404.

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

Library locations in a category near an anchor location, nearest first. The advertiser's own locations are left out. advertiser_id is the Quorum advertiser id; the anchor must be configured for it in your agency and have coordinates, otherwise 404.

Fields: segment_md5, name, brand, category, distance_miles, lat, lon, address, city, state, dma_name, visits_30d, household_count_60d.

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

Add or update your advertisers, keyed on your own client_advertiser_id. A new id opens a PENDING mapping that Quorum completes; nothing is ever deleted. The same id twice in one request is a 400.

Response: accepted, new_client_advertiser_ids.

curl -X POST https://api.quorum.live/v1/intake/advertisers \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"qurum_ag_id": 1234, "records": [{"client_advertiser_id": 12345, "client_advertiser_name": "Example Brand", "website": "example.com"}]}'

Your advertisers and their Quorum mapping. Optional client_advertiser_id filter. Fields: client_advertiser_id, client_advertiser_name, website, status, quorum_advertiser_id (null until mapped), mapping_status (PENDING | MAPPED | IGNORED), mapped_at, location_count, status_updated_at.

curl "https://api.quorum.live/v1/intake/advertisers?client_advertiser_id=12345" \
  -H "Authorization: Bearer <token>"

From the next request on, every route that reads this advertiser returns 410, whether you call it with your own advertiser id or the Quorum advertiser id: /locations, /visits, /report, /performance/*, /summary and the rest. Nothing is deleted, capture keeps running, and the Quorum advertiser, your stores and their locations are kept. Optional body {"reason": "..."} (kept in Quorum's audit log). Idempotent: repeating it returns 200 with changed: false.

Serves the advertiser again, with its full history, including visits captured while it was disconnected. Same optional body. Idempotent.

The current state. All three return client_advertiser_id, agency_id, status (ACTIVE | RETIRED), connected, status_updated_at, and on POST changed. 404 if the id is unknown to your agency; 403 on the POSTs for a read-only token.

curl -X POST https://api.quorum.live/v1/intake/advertisers/12345/disconnect \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"reason": "campaign paused"}'
curl https://api.quorum.live/v1/intake/advertisers/12345/connection \
  -H "Authorization: Bearer <token>"

Send your stores. Add-only: send the full list or just the new stores. Stores already on file are kept, new ones are added, and a store you leave out is never deleted.

• Your location_name is stored exactly as sent. It is the label Quorum gives back everywhere (GET /v1/intake/locations, and client_location_name on /locations).
• A store row is identified by client_advertiser_id + location_name + address + city + state + zip_code. Re-posting the same row returns the same location_id with created: false.
• A store moves from submitted to pending_draw once its advertiser is mapped and it has a street address plus a ZIP or city and state. Quorum then draws its footprint and it becomes active.

Response

curl -X POST https://api.quorum.live/v1/intake/locations \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"qurum_ag_id": 1234, "records": [{"client_advertiser_id": 12345, "location_name": "Example Brand #12", "address": "123 Main St", "city": "Dallas", "state": "TX", "zip_code": "75201"}]}'

The stores you have posted, one row per store, with their status.

Query parameters

Response: agency_id, status_counts (submitted, pending, active, for the same filters ignoring status and paging), returned, next_after_location_id (null on the last page), and locations[] with location_id, client_advertiser_id, location_name, address, city, state, zip_code, store_url, status, segment_md5s, submitted_at, last_submitted_at, status_updated_at (UTC). No geometry is returned.

curl "https://api.quorum.live/v1/intake/locations?client_advertiser_id=12345&status=active" \
  -H "Authorization: Bearer <token>"

Daily exposure and visit counts for your agency, one row per day × advertiser (or campaign) × metric set. JSON by default, CSV with format=csv or Accept: text/csv.

Row fields: activity_date, agency_id, advertiser_id, advertiser_name, campaign_id, campaign_name, metric_set, impressions, hh_resolved_impressions, det_count, est_count, suppressed, multiplier, multiplier_grain, multiplier_significant, config_status, unique_households_last_touch, source_table, generated_at.

• det_count is measured households, never scaled. est_count = det_count × multiplier, and is null when the multiplier is not statistically significant.
• A row whose det_count is above 0 but under the privacy floor (currently 50 households) has det_count and est_count null and suppressed: true. A 0 always means a verified zero.

curl "https://api.quorum.live/v1/partner-feed/daily?date_from=2026-10-01&date_to=2026-10-31&grain=campaign&format=csv" \
  -H "Authorization: Bearer <token>"

Window totals from the feed for one advertiser, beside its hosted report, so you can tell whether they should match. Params: advertiser_id (Quorum id), date_from, date_to (all required; 31 days max).

Response: advertiser_id, window, feed_total (impressions, det_household_reach, est_household_reach), hosted_report (report_id, report_type, refreshed_at, note, or null), match, match_reason.

curl "https://api.quorum.live/v1/partner-feed/reconcile?advertiser_id=1234&date_from=2026-10-01&date_to=2026-10-31" \
  -H "Authorization: Bearer <token>"

Performance tables

Daily performance rows for one Quorum advertiser, filtered to your agency (an advertiser outside it returns an empty list). Shared parameters: advertiser_id (required), date_from (default 30 days ago), date_to (default today), io_id, li_id, limit.

Fields on every 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.

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

Segments

Location segments configured for a Quorum advertiser in your agency.

Params: advertiser_id (required), limit (default 1000, max 10,000). Fields: agency_id, quorum_advertiser_id, location_type, segment_md5, name, brand, category, entity_type, dma_name.

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

30-day counts per segment, ending 5 days ago for data lag. Params: advertiser_id (required), limit (default 1000). Fields: segment_md5, segment_visitors_30d (distinct households), active_days, total_device_visits.

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

POI segments with household visit stats over date_from..date_to (default the last 90 days). Filters: brand, category, min_households, limit (default 5000, max 50,000). Fields: segment_md5, name, brand, category, entity_type, dma_name, lat, lon, household_count, device_count, first_visit, last_visit.

curl "https://api.quorum.live/v1/advertisers/1234/segments?min_households=1" -H "Authorization: Bearer <token>"

Reference data

zip_code, city, state, state_name, county, dma_code, dma_name, population, population_density, latitude, longitude. 404 if unknown.

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

For a 15-digit FIPS block: census_block_id, zip_code, city, state, state_name, state_fips, county_fips, tract_fips, dma_code, dma_name, zip_population. 404 if unknown.

Library metadata for any segment_md5: segment_name, brand, category, dma_name, zip_code, region, visits_30d, source_agency_id, source_advertiser_id. 404 if not in the library.

Location library

Aggregate data on Quorum's reference library of tracked US locations (brands, categories, DMAs). Open-ended questions go to the Quorum MCP at https://mcp.quorum.live/mcp; the library's free-text question route has been removed.

curl "https://api.quorum.live/v1/library/categories?limit=10"

Audience intelligence reports

The published brand audience-intelligence reports: {"reports": [...], "count": N}.

One report as JSON: master, headline_stats, dma_distribution, category_affinity, cross_shopping, competitive_set, narratives. 404 for an unknown slug.

These are brand-level reports, not your campaign reports; for those see /report.

Internal tokens only

Data freshness