Identity API & HouseholdID

The LtvAdx Identity API resolves device-level signals to a household-level identifier (HouseholdID) using a 7-tier resolution chain. HouseholdIDs power cross-device frequency capping, addressable targeting, and Shapley attribution across CTV, mobile, and web.

Why HouseholdID matters

A typical household has 4–6 connected devices: two smartphones, a smart TV or Roku, a laptop, and a tablet. Without household resolution, a frequency cap of 3 impressions per day could actually show the same household 3× on each device — 12–18 total exposures. HouseholdID unifies all devices under one identifier, making frequency caps and reach measurement accurate.

7-tier resolution chain

LtvAdx resolves a HouseholdID from any combination of input signals, trying each tier from highest to lowest confidence until a match is found:

Resolving a HouseholdID

Call the resolve endpoint at stream start (for SSAI) or before requesting a VAST tag (for client-side integrations). Pass any combination of known signals — LtvAdx uses the highest-confidence signal available:

POST https://api.ltvadx.com/api/v1/identity/resolve
Authorization: Bearer {apiKey}
Content-Type: application/json

{
  "uid2Hash":       "sha256:a3f9b2c1...",  // highest priority
  "advertisingId":  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ipAddress":      "104.28.42.1",          // resolved server-side
  "userAgent":      "Roku/DVP-9.0 (...)",
  "platform":       "ROKU",
  "publisherId":    "pub_abc"               // for PPID lookup
}

# 200 Response
{
  "householdId":    "hh_a1b2c3",
  "qualityScore":   92,                  // 0–100 confidence
  "resolvedVia":    "UID2",              // resolution tier used
  "deviceCount":    4,
  "segments":       ["sports_fan", "cord_cutter", "binge_watcher"],
  "consentStatus":  "ALLOW_ALL",         // ALLOW_ALL | LIMITED | OPT_OUT
  "ttlSeconds":     86400
}

# 404 — no match found (use contextual-only targeting)
{ "error": "HOUSEHOLD_NOT_FOUND", "fallback": "contextual" }

Using HouseholdID in VAST requests

Pass the resolved householdId in your VAST URL to enable household-level frequency capping, audience targeting, and attribution:

GET https://ads.ltvadx.com/vast
    ?channelId=chan_fast_news_01
    &adBreakId=midroll_1
    &platform=ROKU
    &householdId=hh_a1b2c3    ← resolved HouseholdID
    &ifa=xxxxxxxx-xxxx-...
    &duration=30

ACR signal ingestion

Automatic Content Recognition (ACR) data enriches household segments with linear TV viewing history. Ingest ACR signals to power TV-exposed audience targeting:

POST https://api.ltvadx.com/api/v1/identity/acr-signal
Authorization: Bearer {apiKey}
Content-Type: application/json

{
  "householdId":         "hh_a1b2c3",
  "channelId":           "nbc_live",          // your ACR channel identifier
  "contentFingerprint":  "cfp_xyz789",        // audio fingerprint or content ID
  "tuneInAt":            "2026-06-03T20:30:00Z",
  "tunedOutAt":          "2026-06-03T21:30:00Z",
  "genre":               "SPORTS",
  "network":             "NBC",
  "programTitle":        "Sunday Night Football"
}

# 200 — signal accepted
{ "status": "INGESTED", "segmentUpdates": ["sports_fan", "nfl_viewer"] }

Household segments

Each HouseholdID accumulates audience segments based on viewing history, ACR signals, and inferred interests. Segments are used by advertisers to target line items via targetTvExposedSegments in the line item targeting configuration.

# Get segments for a household
GET https://api.ltvadx.com/api/v1/identity/household/{householdId}/segments
Authorization: Bearer {apiKey}

# Response
{
  "householdId": "hh_a1b2c3",
  "segments": [
    { "id": "sports_fan",      "confidence": 0.95, "lastSeen": "2026-06-03" },
    { "id": "cord_cutter",     "confidence": 0.88, "lastSeen": "2026-06-01" },
    { "id": "nfl_viewer",      "confidence": 0.91, "lastSeen": "2026-06-03" },
    { "id": "binge_watcher",   "confidence": 0.82, "lastSeen": "2026-05-30" },
    { "id": "premium_spender", "confidence": 0.71, "lastSeen": "2026-05-28" }
  ]
}

Consent and opt-out

Identity resolution respects consent signals. Pass TCF 2.2, CCPA, or LMT flags in VAST requests (see Security & RBAC guide). When lmt=1 or CCPA opt-out is set:

• No HouseholdID is written or updated for the request.
• Frequency capping reverts to device-level only.
• Audience segment targeting is disabled; contextual targeting applies.
• The ACR ingestion endpoint returns 403 Consent Required.

Viewers can opt out permanently via LtvAdx Ad Choices. Opt-outs are applied to the HouseholdID and persist for 2 years before requiring re-confirmation.

Identity graph dashboard

Network admins can look up any HouseholdID in the dashboard at Admin Portal → Household Lookup. Enter an IP address, advertising ID, or UID2 hash to see the resolved household card: device graph, quality score, segments, consent status, and recent impressions.