Identity API & HouseholdID

A HouseholdID is the key LtvAdx uses for frequency caps and audience targeting. Send the same one on every ad request from a household's devices and caps apply across all of them.

Where the HouseholdID comes from

The ad server never resolves identity itself — it uses the householdId on the VAST request. You can keep your own household ids, or ask the Identity API to create or look one up. A request without a householdId is anonymous: no frequency cap and no audience targeting apply.

Resolving a HouseholdID

Call it from your backend (API keys must not ship in app binaries):

POST https://api.ltvadx.com/api/v1/identity/resolve
Authorization: Bearer ltv_live_…            # your API key (publisher or admin account)
Content-Type: application/json

{
  "deviceId":      "DEVICE_ID",             // checked first
  "ip":            "203.0.113.10",          // checked second
  "platform":      "ROKU",
  "advertisingId": "…",                     // stored with a new device record
  "ppid":          "…",                     // stored on a new household
  "uid2Hash":      "…"                      // stored on a new household
}

# 200
{ "householdId": "hh-…", "matchType": "DETERMINISTIC", "confidence": 1.0 }

Order	Match	matchType / confidence
1	deviceId already linked to a household	DETERMINISTIC / 1.0
2	ip already seen on a household	PROBABILISTIC / 0.75
3	nothing matched — a new household is created (and a device link if deviceId and platform are given)	NEW / 1.0

UID2, PPID and advertising IDs

Today these are stored on new records but not used for matching: two devices are joined to one household only through a shared device id or IP. Rate limit: 100 requests per second per caller (429 above it).

Using the HouseholdID in VAST requests

GET https://ads.ltvadx.com/vast
    ?channelId=YOUR_CHANNEL_ID
    &householdId=hh-…
    &platform=ROKU
    &breakType=MID_ROLL
    &duration=30

ACR viewing signals

ACR (automatic content recognition) events can be stored against a household. Every 5 minutes LtvAdx folds new events (views of 2 minutes or more) into the household's genre, network and daypart affinities and segment ids.

POST https://api.ltvadx.com/api/v1/identity/acr-signal
Authorization: Bearer ltv_live_…
Content-Type: application/json

{
  "householdId":         "hh-…",
  "platform":            "SAMSUNG_TIZEN",
  "programTitle":        "…",
  "networkName":         "…",
  "genre":               "Sports",
  "iabContentCategory":  "IAB17",
  "isLive":              true,
  "tuneInAt":            "2026-10-01T14:00:00Z",
  "tuneOutAt":           "2026-10-01T15:00:00Z",
  "viewDurationSeconds": 3600
}

# 201 Created (no body)

ACR targeting is not applied yet

Line items can save TV-exposed segments, but no serve-time filter evaluates them today, and no ACR data provider is integrated. Do not plan delivery around ACR targeting yet.

Household segments (admin)

GET https://api.ltvadx.com/api/v1/identity/household/{householdId}/segments   # NETWORK_ADMIN
→ { "householdId": "hh-…", "segments": ["…", "…"] }

GET https://api.ltvadx.com/api/v1/identity/graph/{deviceId}                   # NETWORK_ADMIN

Consent

POST /api/v1/identity/consent stores gdprConsent, ccpaOptOut and a consentString on a household. Serving does not read them yet, and the VAST endpoint does not read consent parameters — see Security & RBAC.